feat: add GitHub Actions workflow for deploying ShellDocs to GitHub Pages

- Introduced a new workflow in deploy-pages.yml to automate the deployment of the ShellDocs documentation site to GitHub Pages.
- Configured triggers for deployment on pushes to the main branch and manual dispatch.
- Implemented build steps to generate a static site using the shelldocs CLI, including handling of custom domains and Jekyll settings.
- Ensured proper permissions and concurrency management for seamless deployment.

Author: Shewart

.github/workflows/deploy-pages.yml

@@ -0,0 +1,113 @@
+# Publishes the ShellDocs docs site to GitHub Pages (custom domain:
+# shelldocs.shellui.dev). Two triggers: every push to `main`, and manual
+# via workflow_dispatch when you want to re-deploy without a code change.
+#
+# Uses the modern GitHub Pages deploy flow (`actions/upload-pages-artifact`
+# + `actions/deploy-pages`) — no `gh-pages` branch commits, no third-party
+# actions, no PAT juggling. Deploy runs as the Pages OIDC identity in the
+# `github-pages` Environment.
+#
+# ─── Build step ────────────────────────────────────────────────────────
+# `shelldocs build` (as of 0.1.5-alpha) does the real work: `dotnet
+# publish`, then launches the published Blazor Server app on a loopback
+# port, walks NavigationGraph.AllUrls to enumerate every route, HTTP-GETs
+# each URL and saves the rendered HTML per route, then merges
+# publish/wwwroot/ (framework assets + shelldocs.js + tokens CSS) on top.
+# Output is a real static site — every URL is a prerendered HTML file,
+# no .NET host needed at runtime. Server-mode Blazor's client-side JS
+# still boots (shelldocs.js drives theme/search/tabs/copy/collapse
+# without SignalR), so interactive chrome keeps working on Pages.
+
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# GH Pages only serves the most-recently-deployed artifact. Cancel any
+# in-progress deploy when a new push lands so the newest commit wins
+# instead of racing an older one to completion.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+# Required by the deploy-pages action:
+#   pages: write     — upload the artifact + trigger the deploy
+#   id-token: write  — sign the deploy via OIDC (no PAT needed)
+#   contents: read   — checkout
+permissions:
+  pages: write
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    name: Build static site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          # Reads global.json — currently pinned to a 10.0 preview.
+          global-json-file: global.json
+
+      # Pin the CLI version to the same version the site's PackageReferences
+      # use. Prevents a floating latest-prerelease install from silently
+      # shifting the prerender behaviour under our feet mid-release-cycle.
+      - name: Install shelldocs CLI
+        run: dotnet tool install -g ShellDocs.CLI --version 0.1.6-alpha
+
+      # Restore explicitly so the `shelldocs build`'s embedded `dotnet
+      # publish` doesn't spend the first run downloading every package
+      # under a subprocess where its progress output is buried.
+      - name: Restore
+        run: dotnet restore ShellDocs.Site.csproj
+
+      # `shelldocs build` produces the full static site into `./publish/`
+      # by default: prerendered HTML for every route + merged framework
+      # assets. --spa-fallback copies index.html to 404.html so GH Pages
+      # serves the app shell for any URL a bot / typo hits that doesn't
+      # correspond to a prerendered route. --site-url (added in 0.1.6-alpha)
+      # emits a sitemap.xml + robots.txt at the site root and injects
+      # og:title / og:description / og:url / og:type into every rendered
+      # page's <head> so link previews on social / chat look right. No
+      # --base-href flag: we're on a custom root domain
+      # (shelldocs.shellui.dev), so `<base href="/">` from the source is
+      # already correct.
+      - name: Build static site
+        run: shelldocs build --spa-fallback --site-url https://shelldocs.shellui.dev
+
+      # Custom domain: GH Pages reads a `CNAME` file at the site root and
+      # keeps the domain wired across deploys. Written here (not committed
+      # to the repo) so nothing in source needs to know the deploy URL.
+      - name: Write CNAME
+        run: echo "shelldocs.shellui.dev" > publish/CNAME
+
+      # `.nojekyll` disables GitHub's default Jekyll build. Blazor's output
+      # includes files whose names start with `_` (`_framework/`,
+      # `_content/`) — Jekyll would silently exclude those from the served
+      # site, breaking every JS/CSS asset. Ship the flag file to opt out.
+      - name: Disable Jekyll
+        run: touch publish/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: publish
+
+  deploy:
+    name: Deploy to Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      # The `github-pages` environment is auto-created by the deploy
+      # action; its URL is where the deploy landed.
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4