chore: update ShellDocs package versions and enable XML documentation… #1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # 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 |