GitHub Pages

Page content:

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:

.github/workflows/docs.ymlyaml
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@v5

postdoc 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

  1. actions/checkout and actions/setup-node put your code and Node.js on the runner, and npm ci installs Postdoc and Nightwatch.
  2. npx postdoc check checks the pages and their links, in seconds, and npx postdoc test builds the site into out/ and checks it in a browser. If a check fails, the workflow stops there, and the site that's live stays as it is.
  3. actions/upload-pages-artifact packs the out/ folder, and actions/deploy-pages publishes 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.

Edit this page on GitHub