GitHub Pages
GitHub Pages can publish the build from a workflow. A project site is served from a subfolder named after the repository, such as username.github.io/my-project/, so set base to '/my-project/'. A user or organisation site (username.github.io) or a custom domain is served from the root and needs no base.
The workflow
In the repository settings, under Pages, set the source to GitHub Actions, and add .github/workflows/docs.yml:
name: Deploy docs
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx postdoc check
- run: npx postdoc test
- uses: actions/upload-pages-artifact@v5
with:
path: out
- id: deployment
uses: actions/deploy-pages@v5postdoc test builds the site and checks it, so the workflow only deploys a build that passed. Use npx postdoc build instead to deploy without the checks.
What the workflow does
actions/checkoutandactions/setup-nodeput your code and Node.js on the runner, andnpm ciinstalls Postdoc and Nightwatch.npx postdoc checkchecks the pages and their links, in seconds, andnpx postdoc testbuilds the site intoout/and checks it in a browser. If a check fails, the workflow stops there, and the site that's live stays as it is.actions/upload-pages-artifactpacks theout/folder, andactions/deploy-pagespublishes it.
The permissions let the workflow publish to Pages, and the github-pages environment shows the site's address on the workflow run.
Check pull requests too
This workflow runs when a change reaches main. To check pull requests before they're merged, add the workflow from Testing in CI, which runs the checks without deploying anything.
A 404 page
GitHub Pages shows the 404.html at the root of the site for an address that doesn't exist. A layout at layouts/404.ejs gives the site one, see A 404 page.