Migrate tutorials

.github/workflows/deploy-docs.yml

@@ -0,0 +1,65 @@
+name: Deploy MyST Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "tutorials/**"
+      - ".github/workflows/deploy-docs.yml"
+  workflow_dispatch: # Allow manual trigger
+
+env:
+  # For custom domain docs.commontools.dev, we don't need a subfolder
+  BASE_URL: ""
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: tutorials/package-lock.json
+
+      - name: Install dependencies
+        working-directory: tutorials
+        run: npm ci
+
+      - name: Build MyST site
+        working-directory: tutorials
+        run: npm run build
+
+      - name: Copy CNAME to build directory
+        run: cp tutorials/CNAME tutorials/_build/html/CNAME
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "tutorials/_build/html"
+
+  deploy:
+    # Only deploy from main branch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CNAME

@@ -0,0 +1 @@
+docs.commontools.dev

deno.json

@@ -91,7 +91,8 @@
       "packages/static/assets/",
       "packages/ts-transformers/test/fixtures",
       "packages/schema-generator/test/fixtures",
-      "packages/vendor-astral"
+      "packages/vendor-astral",
+      "tutorials/"
     ]
   },
   "imports": {

tutorials/.gitignore

@@ -0,0 +1,7 @@
+# Node / tooling
+node_modules/
+npm-debug.log*
+
+# Myst build output
+_build/
+.cache/

tutorials/.nvmrc

@@ -0,0 +1 @@
+18

tutorials/CNAME

@@ -0,0 +1 @@
+docs.commontools.dev

tutorials/README.md

@@ -0,0 +1,14 @@
+# Tutorials
+
+Install MyST Markdown tooling by following https://mystmd.org/guide/installing. Once set up, run `myst` in this directory to serve the tutorial pages locally.
+
+## npm quickstart
+
+```sh
+npm i
+npm run dev
+```
+
+TODO:
+* Add document on how Input and Output schemas work for Recipes
+* Chapter on basic UI and existing ct components

tutorials/README_BUILD.md

@@ -0,0 +1,53 @@
+# Documentation Build Process
+
+This directory contains the MyST documentation that gets built and deployed to https://docs.commontools.dev
+
+## Overview
+
+While the main codebase uses Deno, the documentation is built using MyST (mystmd), which is a Node.js-based static site generator for scientific and technical documentation.
+
+## GitHub Actions Deployment
+
+The documentation is automatically built and deployed via GitHub Actions when:
+- Changes are pushed to the `main` branch
+- The changes affect files in the `tutorials/` directory
+- Or when manually triggered via workflow dispatch
+
+The workflow is defined in `.github/workflows/deploy-docs.yml`
+
+## Local Development
+
+To work on the documentation locally, you'll need Node.js (not Deno) for MyST:
+
+```bash
+# Navigate to tutorials directory
+cd tutorials
+
+# Install dependencies (requires Node.js)
+npm install
+
+# Start development server
+npm run dev
+
+# Build static site
+npm run build
+```
+
+## Configuration
+
+- **MyST Config**: `myst.yml` - Defines the site structure and settings
+- **Custom Domain**: The CNAME file configures the custom domain (docs.commontools.dev)
+- **GitHub Pages**: The site is deployed to GitHub Pages with the custom domain
+
+## Important Notes
+
+1. The MyST build process is completely separate from the Deno-based application code
+2. The GitHub Action uses Node.js to build the documentation
+3. The built HTML is deployed to GitHub Pages
+4. Make sure to configure DNS records to point `docs.commontools.dev` to GitHub Pages
+
+## DNS Configuration Required
+
+For the custom domain to work, you need to configure DNS:
+- Add a CNAME record pointing `docs.commontools.dev` to `<username>.github.io`
+- Or configure it according to GitHub's custom domain documentation

tutorials/code/state_02.tsx

@@ -0,0 +1,47 @@
+/// <cts-enable />
+import {
+  cell,
+  h,
+  recipe,
+  UI,
+  lift,
+  derive,
+  handler,
+  type Cell,
+} from "commontools";
+
+const calcAC = (dex: number) : number =>
+  20 + Math.floor((dex - 10) / 2);
+
+const updateName = handler<
+  { detail: { message: string } },
+  { characterName: Cell<string> }
+>(
+  (event, { characterName }) => {
+    console.log("Updating character name to:", event.detail.message);
+    characterName.set(event.detail.message);
+  }
+);
+
+export default recipe("state test", () => {
+  const characterName = cell<string>("");
+  characterName.set("Lady Ellyxir");
+  const dex = cell<number>(16);
+  const ac = lift(calcAC)(dex);
+
+  return {
+    [UI]: (
+      <div>
+        <h2>Character name: {characterName}</h2>
+        <common-send-message
+          name="Update"
+          placeholder="Update Name"
+          onmessagesend={updateName({ characterName })}
+        />
+        <li>DEX: {dex}</li>
+        <li>DEX Modifier: {Math.floor((dex - 10) / 2)}</li>
+        <li>AC: {ac}</li>
+      </div>
+    ),
+  };
+});

tutorials/code/state_03.tsx

@@ -0,0 +1,65 @@
+/// <cts-enable />
+import {
+  cell,
+  h,
+  recipe,
+  UI,
+  lift,
+  derive,
+  handler,
+  type Cell,
+} from "commontools";
+
+const calcAC = (dex: number) : number =>
+  20 + Math.floor((dex - 10) / 2);
+
+const updateName = handler<
+  { detail: { message: string } },
+  { characterName: Cell<string> }
+>(
+  (event, { characterName }) => {
+    characterName.set(event.detail.message);
+  }
+);
+
+const rollD6 = () => Math.floor(Math.random() * 6) + 1;
+
+const rollDex = handler<
+  unknown,
+  Cell<number>
+>(
+  (_, dex) => {
+    // Roll 3d6 for new DEX value
+    const roll = rollD6() + rollD6() + rollD6();
+    dex.set(roll);
+  }
+);
+
+export default recipe("state test", () => {
+  const characterName = cell<string>("");
+  characterName.set("Lady Ellyxir");
+  const dex = cell<number>(16);
+  const ac = lift(calcAC)(dex);
+
+  return {
+    [UI]: (
+      <div>
+        <h2>Character name: {characterName}</h2>
+        <common-send-message
+          name="Update"
+          placeholder="Update Name"
+          onmessagesend={updateName({ characterName })}
+        />
+        <li>
+          DEX: {dex}
+          {" "}
+          <ct-button onClick={rollDex(dex)}>
+            Roll
+          </ct-button>
+        </li>
+        <li>DEX Modifier: {Math.floor((dex - 10) / 2)}</li>
+        <li>AC: {ac}</li>
+      </div>
+    ),
+  };
+});