Publish docs/guide as GitHub Pages with MkDocs Material (#402)

Add the MkDocs + GitHub Actions pipeline to publish docs/guide as a
browsable site at https://microsoft.github.io/microsoft-ui-reactor/.

Compiler:
- DocAssembler.Assemble now takes the page's topicId so screenshot://
  refs in subdir pages (recipes/*) emit correct ../images/ paths.
- The compiler also writes README.md alongside index.md so GitHub's
  directory browser renders the landing page at docs/guide/.

Template fixes (for both raw GitHub MD viewing and the MkDocs site):
- Convert out-of-tree refs (../specs/*, ../contributing/*,
  ../reference/async-system.md, _pipeline/ai-author-skill.md) to
  absolute https://github.com/microsoft/microsoft-ui-reactor/blob/main/
  URLs so links work after docs/guide is published as a standalone
  site.
- Redirect stale async-resources-cookbook.md references to
  async-resources.md (page was renamed per topic table in
  docs/_pipeline/ai-author-skill.md).
- Drop the broken reference/elements/index.md link in components.md.dt
  (that reference axis category has not been generated yet).
- Rename readme.md.dt -> index.md.dt so the compiled site root URL
  resolves, and update the three inbound readme.md links accordingly.

Stale generated output:
- Remove docs/guide/async-resources-cookbook.md (no template; renamed).

Adds:
- mkdocs.yml with Material theme and curated nav matching the readme's
  10-section structure.
- docs/requirements.txt pinning mkdocs, mkdocs-material, pymdown.
- .github/workflows/docs.yml building with --strict on push to main
  (paths-filtered to docs/guide/**, mkdocs.yml, requirements.txt, the
  workflow itself) and deploying via actions/deploy-pages@v4.

After merging, enable Pages in Settings -> Pages -> Source: GitHub
Actions.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: codemonkeychris

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Publish docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/guide/**'
+      - 'mkdocs.yml'
+      - 'docs/requirements.txt'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -238,3 +238,6 @@ tests/stress_perf/baselines/**/per-rep.csv
 # output, both regenerated on every build.
 tests/stress_perf_rn/**/Bundle/
 tests/stress_perf_rn/**/Generated Files/
+
+# MkDocs build output
+/site/

docs/_pipeline/templates/_skeletons/stub.md.dt

@@ -29,7 +29,7 @@ tier: stub
 # {{REPLACE_ME: human-readable title}}
 
 Coming soon — this page documents {{REPLACE_ME: feature or topic}}. See
-[the AI Author Skill](../../_pipeline/ai-author-skill.md) for the planned
+[the AI Author Skill](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/_pipeline/ai-author-skill.md) for the planned
 surface area and the spec-041 §7.1 layout it slots into.
 
 In the meantime, the closest existing coverage is

docs/_pipeline/templates/async-resources.md.dt

@@ -28,7 +28,7 @@ unmount, shared caching across siblings, and stale-while-revalidate by default.
 | `PendingFactory.Pending` | Hold a fallback in place until every nested resource leaves `Loading` |
 
 For the full state-machine reference, see
-[async-system.md](../reference/async-system.md). This page is task-oriented:
+[async-system.md](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/reference/async-system.md). This page is task-oriented:
 each section is a recipe you can copy.
 
 ## Porting UseEffect + UseState → UseResource

docs/_pipeline/templates/collections.md.dt

@@ -218,7 +218,7 @@ receive is the full current selection, not the change since the last call.
 Passing `null` to the fluent clears any previously-set handler.
 
 > `TreeView` multi-select is intentionally deferred — see
-> [spec 039](../specs/039-property-and-event-scrub.md) §5.8 for the
+> [spec 039](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/specs/039-property-and-event-scrub.md) §5.8 for the
 > rationale. Use single-select `OnItemInvoked` until then.
 
 ## Stable Identity with WithKey

docs/_pipeline/templates/components.md.dt

@@ -46,8 +46,9 @@ with a `Render()` method that returns an element tree describing its UI.
 Override `ShouldUpdate(TProps? old, TProps? new)` to make a `Component<TProps>`
 ignore certain prop changes (cosmetic-only label updates, for example). The
 default `Equals()`-based check on records is the right call for most cases.
-The auto-generated [components reference](reference/elements/index.md) covers
-every member; the rest of this page is the narrative.
+The auto-generated components reference covers every member (coming soon —
+see the [Hooks reference](reference/hooks/index.md) for the existing
+prototype); the rest of this page is the narrative.
 
 ## Basic Component
 

docs/_pipeline/templates/dev-tooling.md.dt

@@ -116,7 +116,7 @@ subcommands map one-to-one to the workflows below.
 | `mur pack-local` / `mur clean-local` | Package / clean the local NuGet feed for samples that consume `Microsoft.UI.Reactor` as a package | `mur pack-local` |
 
 `mur docs compile` is the workflow you reach for most often. See
-[the doc-pipeline contributor guide](../contributing/doc-pipeline.md)
+[the doc-pipeline contributor guide](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/contributing/doc-pipeline.md)
 for the full surface and the `--validate-only`, `--skip-screenshots`,
 `--skip-diagrams`, `--skip-reference`, and `--tier=<stub|solid|comprehensive>`
 flags that make the inner loop fast.
@@ -132,7 +132,7 @@ you launch it explicitly when you want agent integration.
 
 The deeper protocol surface lives in
 [DevTools Internals](devtools-internals.md). The
-[`docs/contributing/devtools.md`](../contributing/devtools.md) guide is
+[`docs/contributing/devtools.md`](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/contributing/devtools.md) guide is
 the operational reference (how to plug it into Claude Desktop / VS Code).
 
 ## VS Code Panel
@@ -279,7 +279,7 @@ to a dozen flags without a config UI.
 The same preview-mode plumbing the doc pipeline uses is available to
 your own app: pass `preview: true` to `ReactorApp.Run` and the doc-
 pipeline screenshot harness can capture the window. See
-[`docs/contributing/doc-pipeline.md`](../contributing/doc-pipeline.md)
+[`docs/contributing/doc-pipeline.md`](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/contributing/doc-pipeline.md)
 for the harness contract. This is how every page in the docset gets
 its screenshots automatically without an author launching the app by
 hand.

docs/_pipeline/templates/docking.md.dt

@@ -187,4 +187,4 @@ control yourself.
   `WindowPersistedScope` that docking layouts route through.
 - **[Components](components.md)** — `Key` rules and the reconciler
   identity model that `DockableContent.Key` plugs into.
-- **[Reactor](readme.md)** — back to the docset index.
+- **[Reactor](index.md)** — back to the docset index.

docs/_pipeline/templates/effects-scheduling.md.dt

@@ -34,7 +34,7 @@ This page is about when [`UseEffect`](hooks.md) fires and why.
 Surface-level usage is on the [Effects](effects.md) page; the
 async-resource pipeline — `UseResource`, `UseInfiniteResource`,
 `Pending`, `QueryCache` — has its own deep walk in the
-[async-system reference](../reference/async-system.md). What
+[async-system reference](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/reference/async-system.md). What
 follows is the render-loop view of the same callbacks.
 
 ## The render → commit → flush sequence
@@ -119,7 +119,7 @@ paths don't collide:
 
 `PendingScope` is one place the cleanup contract is load-bearing. A
 `UseResource` hook registers its token with the nearest ancestor
-[`Pending`](async-resources-cookbook.md) scope at mount, updates
+[`Pending`](async-resources.md) scope at mount, updates
 loading state through its lifecycle, and unregisters in cleanup.
 Skip the unregister and the `Pending` fallback never clears — the
 fallback subtree stays rendered after the resource resolves because
@@ -148,7 +148,7 @@ UseEffect(async () => {              // async void lambda
 The async-resource hooks (`UseResource`, `UseInfiniteResource`,
 `UseMutation`) wrap this pattern correctly — they own the cancellation
 token, marshal completions back to the UI thread, and clean up their
-[`QueryCache`](async-resources-cookbook.md) subscription on unmount.
+[`QueryCache`](async-resources.md) subscription on unmount.
 Reach for them before writing async-effect glue by hand. When you do
 need a raw `UseEffect` for an async operation, the cleanup function
 is your only chance to cancel the in-flight task — capture a
@@ -260,7 +260,7 @@ the next render leaks the resource.
 **Don't await directly in the lambda.** `UseEffect(async () => ...)`
 detaches from the flush ordering; capture a `CancellationTokenSource`,
 kick off a `Task.Run`, and cancel in cleanup. Or use
-[`UseResource`](async-resources-cookbook.md), which already does this.
+[`UseResource`](async-resources.md), which already does this.
 
 **Treat the dep array as a value-equality contract.** Records,
 primitives, and stable setter identities are safe. Freshly-allocated
@@ -276,6 +276,6 @@ before my body did?" question.
 
 - **[Effects](effects.md)** — Previous: the surface lifecycle of `UseEffect`.
 - **[Reconciliation](reconciliation.md)** — Next: the commit phase that flush runs after.
-- **[Async resources](async-resources-cookbook.md)** — Hooks built on top of this scheduling.
-- **[async-system reference](../reference/async-system.md)** — Deep walk through cache, refcount, and revalidation.
+- **[Async resources](async-resources.md)** — Hooks built on top of this scheduling.
+- **[async-system reference](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/reference/async-system.md)** — Deep walk through cache, refcount, and revalidation.
 - **[Threading and dispatch](threading-and-dispatch.md)** — Why effect bodies always run on the UI thread.

docs/_pipeline/templates/forms.md.dt

@@ -103,7 +103,7 @@ so you rarely need `.Set(...)`. The named-input shapes set the appropriate
 
 These fluents chain freely; the named-input shapes are the canonical way to
 hint mobile / touch keyboards instead of reaching for `.Set(c => c.InputScope = ...)`.
-See [spec 039](../specs/039-property-and-event-scrub.md) §2.3 and §4.7 for the
+See [spec 039](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/specs/039-property-and-event-scrub.md) §2.3 and §4.7 for the
 rationale.
 
 ## Simple Validation