Rework the SDK guide: example app, localhost development, generated API reference

.github/workflows/ci.yml

@@ -78,6 +78,13 @@ jobs:
       - name: Install website dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Check the Worklog example and the generated API reference
+        run: |
+          npm ci --prefix examples/worklog
+          npm run check --prefix examples/worklog
+          npm run build --prefix examples/worklog
+          pnpm check:sdk-api
+
       - name: Build contract catalog
         working-directory: .sources/mdbase-contracts
         run: npm ci && npm run build

README.md

@@ -58,6 +58,25 @@ remain traceable to the release artifacts they document.
 The first-party contract catalog is built from the commit pinned in
 `site-sources.json`, then published as static files under `/contracts/`.
 
+## SDK guide example and API reference
+
+`examples/worklog` is the app the SDK tutorial builds. The tutorial and the
+other SDK pages import their listings from its files, so a listing cannot drift
+from code that compiles. CI installs, type-checks and builds it.
+
+```sh
+cd examples/worklog
+npm ci
+npm run dev      # http://localhost:5173, against production mdbase
+npm run build    # WORKLOG_ORIGIN=https://… sets the deployed origin
+```
+
+`/sdk/api/` is rendered from `src/data/sdk-api.json`, which
+`pnpm build:sdk-api` reads out of the type declarations of the
+`@mdbase-dev/sdk` version the example installs. After changing that version,
+run `npm install` in `examples/worklog`, then `pnpm build:sdk-api`, and commit
+both. CI fails (`pnpm check:sdk-api`) when the committed file is stale.
+
 ## Connect release updates
 
 A published Connect desktop release dispatches its immutable tag to

examples/worklog/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+src/mdbase-app.json

examples/worklog/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Worklog</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

examples/worklog/mdbase/types/worklog-entry.md

@@ -0,0 +1,21 @@
+---
+kind: mdbase.type
+name: worklog-entry
+version: 1
+description: One entry in a work log.
+schema:
+  dialect: json-schema-2020-12
+  value:
+    $schema: https://json-schema.org/draft/2020-12/schema
+    type: object
+    additionalProperties: true
+    required: [date, summary]
+    properties:
+      date: { type: string, format: date }
+      summary: { type: string, minLength: 1 }
+      minutes: { type: integer, minimum: 0 }
+---
+
+# Worklog entry
+
+What was done on one day, and optionally how long it took.