docs(site): auto-regen hooks, auto sidebars, e2e route check

.github/workflows/docs.yml

@@ -59,15 +59,25 @@ jobs:
         working-directory: docs
         run: npm ci
 
+      # Drift gate runs before regen — rationale lives in generate-reference.sh.
+      - name: Verify reference pages match source (drift gate)
+        run: bash docs/scripts/generate-reference.sh --check
+
+      # Generate the docfx-driven /api/ tree and the Roslyn-driven
+      # /reference/ tree HERE — in the only job that has both the .NET SDK
+      # and docfx installed. The downstream Build VitePress site and
+      # Check internal links jobs receive the populated tree via the
+      # `generated-docs` artefact; they neither install dotnet nor docfx,
+      # so they cannot regenerate. The `prebuild` npm hook in
+      # docs/package.json is for local dev only (where `npm run build`
+      # implicitly regenerates); the workflow's Build step invokes
+      # VitePress directly to skip that hook.
       - name: Generate API reference
         run: bash docs/scripts/generate-api-ref.sh
 
       - name: Regenerate auto-generated reference pages
         run: bash docs/scripts/generate-reference.sh
 
-      - name: Verify reference pages match source (drift gate)
-        run: bash docs/scripts/generate-reference.sh --check
-
       # upload-artifact@v4 strips the longest common prefix from the path list
       # (here: 'docs/'), so the artifact root contains 'api/' + 'reference/'
       # rather than 'docs/api/' + 'docs/reference/'. The downstream
@@ -118,9 +128,15 @@ jobs:
         if: github.event_name == 'push' && github.ref == 'refs/heads/master'
         uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6.0.0
 
+      # Invoke VitePress directly rather than `npm run build` to skip the
+      # `prebuild` npm hook in docs/package.json. That hook regenerates
+      # the /api/ + /reference/ trees, which requires the .NET SDK and
+      # docfx — neither of which is installed in this job. The
+      # `generated-docs` artefact downloaded above already contains the
+      # freshly regenerated content from the prepare-docs job.
       - name: Build site
         working-directory: docs
-        run: npm run build
+        run: npx vitepress build
         env:
           DOCS_BASE: /MTConnect.NET/
 

.github/workflows/dotnet.yml

@@ -65,6 +65,35 @@ jobs:
             8.0.x
             9.0.x
 
+      # MTConnect.NET-Docs-Tests carries a Category=E2E route walk
+      # whose [OneTimeSetUp] runs `npm ci && npm run build` from
+      # docs/ when the dist/ artifact is missing, then drives
+      # `vitepress preview` through Microsoft.Playwright. Only the
+      # ubuntu-latest leg runs Category=E2E (the windows-latest leg
+      # excludes it via testFilter), so Node is only required there.
+      - name: Setup Node.js (docs e2e prerequisite)
+        if: matrix.os == 'ubuntu-latest'
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      # `npm run build` in docs/ invokes the `prebuild` hook
+      # (`npm run regen`), which calls `bash scripts/generate-api-ref.sh`
+      # → `docfx metadata` to produce the /api/ reference tree the
+      # VitePress site consumes. The Docs-site workflow installs docfx
+      # in its Prepare job; this workflow's E2E leg needs it for the
+      # same reason. Only the ubuntu-latest leg runs Category=E2E
+      # (windows-latest excludes it via testFilter), so docfx is only
+      # required there. Without this, RouteCheckTests.OneTimeSetUp
+      # fails with "docfx not found on PATH and ~/.dotnet/tools/docfx
+      # is missing" — see PR #181 run 26831500675 job 79113784371.
+      - name: Install docfx (docs e2e prerequisite)
+        if: matrix.os == 'ubuntu-latest'
+        run: dotnet tool install -g docfx
+        shell: bash
+
       - name: Restore dotnet tools (ReportGenerator)
         run: dotnet tool restore
 
@@ -74,6 +103,34 @@ jobs:
       - name: Build (Debug)
         run: dotnet build MTConnect.NET.sln --configuration Debug --no-restore
 
+      # Cache Playwright browser binaries so the Category=E2E
+      # [OneTimeSetUp] `playwright install chromium` call is a no-op on
+      # cache hit. The key hashes the `playwright-core` package.json that
+      # the Microsoft.Playwright NuGet copies into the build output —
+      # that file's `version` field directly pins the chromium revision
+      # the .NET binding drives. Hashing the csproj instead would only
+      # invalidate by coincidence (a future PR adding an unrelated
+      # PackageReference would invalidate; an SDK-side change to the
+      # chromium revision would not). The step therefore runs AFTER
+      # `dotnet build` so the file exists — placement before build
+      # would force the key off a workspace-internal artefact (hashFiles
+      # cannot reach the NuGet cache under ~/.nuget), so the
+      # micro-optimisation of overlapping cache restore with build is
+      # sacrificed for key correctness.
+      # Both Linux (~/.cache/ms-playwright) and Windows
+      # (%USERPROFILE%\AppData\Local\ms-playwright) paths are listed;
+      # actions/cache restores only the path that exists on the running
+      # OS, so the multi-path entry is safe for both matrix legs.
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+            ~\AppData\Local\ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('**/tests/MTConnect.NET-Docs-Tests/bin/Debug/net8.0/.playwright/package/package.json') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-
+
       # MTConnect.NET-Integration-Tests is skipped here (its
       # IsTestProject is false unless IntegrationCoverage=true) and run
       # in the dedicated step below so it can use its own

.gitignore

@@ -320,6 +320,7 @@ $RECYCLE.BIN/
 node_modules/
 docs/.vitepress/cache/
 docs/.vitepress/dist/
+docs/.vitepress/.temp/
 
 # docfx-generated API reference (regenerated by docs/scripts/generate-api-ref.sh
 # on every CI run; keep the section index but ignore the per-type pages).

docs/.vitepress/config.ts

@@ -1,5 +1,6 @@
 import { defineConfig } from 'vitepress';
 import { withMermaid } from 'vitepress-plugin-mermaid';
+import { apiSidebar, referenceSidebar } from './sidebar';
 
 /**
  * VitePress config for the MTConnect.NET documentation site.
@@ -13,10 +14,15 @@ import { withMermaid } from 'vitepress-plugin-mermaid';
  *
  * @remarks
  * The auto-generated reference section (`/reference/`) is produced by
- * `build/MTConnect.NET-DocsGen` at docs-build time; do not edit those
- * pages by hand. Adding a new section here that should also feed the
- * sidebar — extend both the top `nav:` list and the matching entry in
- * `sidebar:`.
+ * `build/MTConnect.NET-DocsGen` at docs-build time; the docfx-driven
+ * API reference (`/api/`) is produced by `docs/scripts/generate-api-ref.sh`.
+ * Do not edit those pages by hand. Both sidebars are derived from
+ * the generated output by `./sidebar.ts` — adding a new generated
+ * page surfaces automatically once the regen scripts have produced
+ * it (the npm `predev` / `prebuild` hooks run them on every dev
+ * server boot and build). Hand-curated narrative sections still
+ * extend the top `nav:` list plus the matching `sidebar:` entry
+ * below.
  *
  * @see {@link https://vitepress.dev/reference/site-config}
  */
@@ -124,24 +130,14 @@ export default withMermaid(
             ],
           },
         ],
-        '/api/': [
-          {
-            text: 'API reference',
-            items: [{ text: 'Overview', link: '/api/' }],
-          },
-        ],
-        '/reference/': [
-          {
-            text: 'Auto-generated reference',
-            items: [
-              { text: 'Overview', link: '/reference/' },
-              { text: 'HTTP API', link: '/reference/http-api' },
-              { text: 'Environment variables', link: '/reference/environment-variables' },
-              { text: 'Configuration schema', link: '/reference/configuration' },
-              { text: 'CLI reference', link: '/reference/cli' },
-            ],
-          },
-        ],
+        // Auto-derived from docfx's toc.yml under docs/api/. Hierarchical
+        // by namespace dots, collapsed by default so the 1800-odd type
+        // pages do not flood the viewport.
+        '/api/': apiSidebar(),
+        // Auto-derived from the .md files under docs/reference/. Flat
+        // alphabetical list so a future page emitted by DocsGen surfaces
+        // without a config-side edit.
+        '/reference/': referenceSidebar(),
         '/wire-formats/': [
           {
             text: 'Wire formats',