Migrate tutorials

[jakedahn]

Summary by cubic

Migrates the tutorials into this repo and sets up a MyST-powered docs site with automatic GitHub Pages deployment at docs.commontools.dev. Adds CI to build on pushes and PRs, plus local tooling for easy authoring.

• New Features

  • Ported tutorials into tutorials/ as a MyST site (index, install-ct, llm-builtin, state, state_modify, common_ui, cts, images, TSX samples).
  • Added site config and tooling: myst.yml, package.json/scripts, package-lock.json, .nvmrc, .gitignore.
  • Configured custom domain via CNAME (docs.commontools.dev).
  • Added GitHub Actions workflow to build and deploy on pushes to main and migrate-tutorials; PRs build for validation only.

• Migration

  • Docs build uses Node/mystmd (separate from the Deno runtime).
  • Local dev: cd tutorials; npm ci; npm run dev. Deployment is handled by CI.

[cubic-dev-ai]

5 issues found across 36 files

Prompt for AI agents (all 5 issues)

Understand the root cause of the following 5 issues and fix them.


<file name="tutorials/cts.md">

<violation number="1" location="tutorials/cts.md:9">
Typo: “succint” should be spelled “succinct.”</violation>
</file>

<file name="tutorials/state.md">

<violation number="1" location="tutorials/state.md:27">
This example also fails to close recipe(), so the snippet is invalid TypeScript. Please end it with `});`.</violation>
</file>

<file name="tutorials/common_ui.md">

<violation number="1" location="tutorials/common_ui.md:266">
Update the ct-screen example to use the header slot so the toolbar renders in the fixed header area.</violation>

<violation number="2" location="tutorials/common_ui.md:310">
Fix the visual components list to refer to ct-kbd so readers use the correct element name.</violation>
</file>

<file name="tutorials/.nvmrc">

<violation number="1" location="tutorials/.nvmrc:1">
Update the .nvmrc to a supported Node.js release (Node 18 went end-of-life on 2025-04-30), so local docs builds run on a maintained runtime.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

Typo: “succint” should be spelled “succinct.”

Prompt for AI agents

Address the following comment on tutorials/cts.md at line 9:

<comment>Typo: “succint” should be spelled “succinct.”</comment>

<file context>
@@ -0,0 +1,15 @@
+keywords: commontools, recipes, cts, types
+abstract: |
+  The CTS (Common Type System) helps automatically convert types and common
+  coding patterns for you. This leads to more readable and succint code.
+  In this section, we will go over the basic features offered by CTS.
+---
</file context>

Suggested change

	coding patterns for you. This leads to more readable and succint code.
	coding patterns for you. This leads to more readable and succinct code.

[cubic-dev-ai]

This example also fails to close recipe(), so the snippet is invalid TypeScript. Please end it with });.

Prompt for AI agents

Address the following comment on tutorials/state.md at line 27:

<comment>This example also fails to close recipe(), so the snippet is invalid TypeScript. Please end it with `});`.</comment>

<file context>
@@ -0,0 +1,230 @@
+```{code-block} typescript
+export default recipe(&quot;state test&quot;, () =&gt; {
+  const characterName = cell&lt;string&gt;(&quot;&quot;);
+}
+```
+Here, we have created a cell with a type argument of `string`,
</file context>

Suggested change

	}
	});

[cubic-dev-ai]

Fix the visual components list to refer to ct-kbd so readers use the correct element name.

Prompt for AI agents

Address the following comment on tutorials/common_ui.md at line 310:

<comment>Fix the visual components list to refer to ct-kbd so readers use the correct element name.</comment>

<file context>
@@ -0,0 +1,365 @@
+- gap: `ct-icon` (and `ct-label` has an optional in-built icon)
+    - gap: icon set?
+
+- visual: `ct-kdb`, `ct-separator`, `ct-table`, `ct-tool-call`
+	- gap: `ct-img` or `ct-media`
+
</file context>

Suggested change

	- visual: `ct-kdb`, `ct-separator`, `ct-table`, `ct-tool-call`
	- visual: `ct-kbd`, `ct-separator`, `ct-table`, `ct-tool-call`

[cubic-dev-ai]

Update the ct-screen example to use the header slot so the toolbar renders in the fixed header area.

Prompt for AI agents

Address the following comment on tutorials/common_ui.md at line 266:

<comment>Update the ct-screen example to use the header slot so the toolbar renders in the fixed header area.</comment>

<file context>
@@ -0,0 +1,365 @@
+
+```{code-block} html
+&lt;ct-screen&gt;
+    &lt;ct-toolbar slot=&quot;top&quot;&gt;
+        &lt;ct-button&gt;hello&lt;/ct-button&gt;
+    &lt;/ct-toolbar&gt;
</file context>

Suggested change

	<ct-toolbar slot="top">
	<ct-toolbar slot="header">

[cubic-dev-ai]

Update the .nvmrc to a supported Node.js release (Node 18 went end-of-life on 2025-04-30), so local docs builds run on a maintained runtime.

Prompt for AI agents

Address the following comment on tutorials/.nvmrc at line 1:

<comment>Update the .nvmrc to a supported Node.js release (Node 18 went end-of-life on 2025-04-30), so local docs builds run on a maintained runtime.</comment>

<file context>
@@ -0,0 +1 @@
+18
</file context>

Suggested change

	18
	20