tbdocs-gh-pages.yml

name: Build & deploy docs

on:
  push:
    branches: ["staging"]

  # Allows you to run this workflow manually from the Actions tab.
  # The manual path additionally cuts a GitHub release with the
  # offline-browsable site copy attached as a zip; pushes to
  # `staging` only deploy to Pages.
  workflow_dispatch:
    inputs:
      release_tag:
        description: 'Release tag (leave blank for auto: docs-YYYY-MM-DD-HHMM in UTC)'
        required: false
        type: string

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22'
          cache: 'npm'
          cache-dependency-path: package-lock.json
      - name: Install dependencies and Chromium
        # fonts-liberation is installed explicitly, not incidentally.
        # axe's target-size rule measures rendered boxes, and an inline
        # element's measured height is its font's content area -- so the
        # 24px floor is cleared or missed depending on what system-ui
        # resolves to. At the mobile h3 size: Segoe UI 19px, Verdana and
        # Tahoma 17px, Arial 16px, Liberation Sans / DejaVu Sans / Roboto
        # 15px. The site's padding is calibrated against the smallest of
        # those, so the runner has to have it. ubuntu-latest migrates to
        # Ubuntu 26 on 19 October 2026; pinning the image would also work
        # and expires differently, while this addresses the actual
        # variable.
        run: |
          npm ci
          sudo apt-get install -y --no-install-recommends fonts-liberation
          sudo npx puppeteer browsers install chrome --install-deps
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v6
      - name: Build and check links with tbdocs
        # --url + --baseurl together make canonical / og:url / sitemap
        # entries point at the actual deployment (e.g. on a fork that
        # deploys to kubao.github.io/twinBASIC-docs/, both bits move
        # so the page advertises its own URL rather than the config'd
        # production host).
        # --no-fetch-assets: CI must never download a referenced image. An
        # author who wrote the markdown but forgot to commit the file would
        # otherwise get a green build while the published site went on
        # hotlinking a third party. A missing asset is a hard failure here,
        # naming the file to commit. ($CI already implies this; the flag
        # states it.) See builder/vendor-assets.mjs.
        #
        # --check runs the link and site-integrity check over the HTML the
        # build already holds in worker memory, across all three trees,
        # instead of writing them out and reading ~270 MB back through
        # scripts/check_links.mjs. Do NOT also add a check_links.mjs pass:
        # it would check the same bytes a second time.
        #
        # --check-audit-index adds the index audit on top: a diff of the
        # tree index the build derives from its own records against what
        # landed on disk. It is the one direction the findings comparison
        # cannot see -- a spurious entry makes the oracle answer "exists"
        # for a path that 404s in production, and on a clean site nothing
        # links to a path that does not exist, so nothing else would
        # notice.
        #
        # It also avoids a synchronisation point that is easy to get wrong:
        # a standalone pass would need --base-path to match this step's
        # --baseurl, in a different step, by hand; the fused check reads the
        # baseurl off the config it just built with. Only the
        # online tree gets a base path -- the offline tree's links are all
        # relative after the rewrite.
        run: node builder/tbdocs.mjs --src docs --url '${{ steps.pages.outputs.origin }}' --baseurl '${{ steps.pages.outputs.base_path }}' --no-fetch-assets --check-audit-index
      # The gates both workflows run, in one list: see
      # .github/actions/run-gates/action.yml, which check_ci_workflows.mjs
      # checks against test.bat and check.bat. checks.yml runs only on pull
      # requests, so this is the one place a change pushed straight to
      # `staging`, or a manual dispatch, meets them. Each gate is its own
      # group in this step's log.
      - name: Run the gates
        uses: ./.github/actions/run-gates
      - name: Render book PDF
        run: |
          mkdir -p _pdf
          node ../book/render-book.mjs _site-pdf/book.html -o "_pdf/twinBASIC Book.pdf" --outline-tags h1,h2,h3,h4 --additional-script ../perf/detach-pages.js
        working-directory: ./docs
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./docs/_site
      # The next two steps run only on manual dispatch -- they
      # package the offline copy of the site (`docs/_site-offline/`,
      # produced by the `also_build_offline: true` flag in
      # `_config.yml`) and ship it as a workflow artifact for the
      # `release` job to attach to a new GitHub release.  Pushes to
      # `staging` skip this and only deploy to Pages.
      - name: Package offline site
        if: github.event_name == 'workflow_dispatch'
        run: |
          if [ ! -d ./docs/_site-offline ]; then
            echo "::error::./docs/_site-offline not found -- ensure also_build_offline is true in _config.yml"
            exit 1
          fi
          (cd ./docs/_site-offline && zip -rq "${{ runner.temp }}/twinbasic-docs-offline.zip" .)
      - name: Upload offline-site workflow artifact
        if: github.event_name == 'workflow_dispatch'
        uses: actions/upload-artifact@v7
        with:
          name: twinbasic-docs-offline-zip
          path: ${{ runner.temp }}/twinbasic-docs-offline.zip
          # Workflow-internal hand-off to the release job; the
          # release itself carries the long-lived copy of the zip.
          retention-days: 7
      - name: Upload book PDF workflow artifact
        uses: actions/upload-artifact@v7
        with:
          name: twinbasic-docs-book-pdf
          path: "./docs/_pdf/twinBASIC Book.pdf"

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

  # Release job -- runs only on manual dispatch, after a successful
  # Pages deploy.  Each manual deploy cuts a new GitHub release whose
  # tag tracks a publicly visible documentation snapshot at
  # https://docs.twinbasic.com, with the offline-browsable copy of
  # the site attached as twinbasic-docs-offline.zip.
  release:
    if: github.event_name == 'workflow_dispatch'
    needs: deploy
    runs-on: ubuntu-latest
    permissions:
      # softprops/action-gh-release needs contents:write to create
      # tags and publish releases.  The top-level permissions block
      # only grants contents:read for the build/deploy path.
      contents: write
    steps:
      - name: Download offline-site workflow artifact
        uses: actions/download-artifact@v8
        with:
          name: twinbasic-docs-offline-zip
      - name: Download book PDF workflow artifact
        uses: actions/download-artifact@v8
        with:
          name: twinbasic-docs-book-pdf
      - name: Compute release tag and name
        id: tag
        env:
          INPUT_TAG: ${{ inputs.release_tag }}
        run: |
          if [ -n "$INPUT_TAG" ]; then
            TAG="$INPUT_TAG"
            NAME="$INPUT_TAG"
          else
            TAG="docs-$(date -u +'%Y-%m-%d-%H%M')"
            NAME="Documentation $(date -u +'%Y-%m-%d %H:%M UTC')"
          fi
          echo "tag=$TAG"   >> "$GITHUB_OUTPUT"
          echo "name=$NAME" >> "$GITHUB_OUTPUT"
      - name: Create release with offline-site zip
        uses: softprops/action-gh-release@v3
        with:
          tag_name: ${{ steps.tag.outputs.tag }}
          name: ${{ steps.tag.outputs.name }}
          target_commitish: ${{ github.sha }}
          body: |
            Snapshot of the documentation deployed to <https://docs.twinbasic.com>.

            **Offline copy:** download `twinbasic-docs-offline.zip`, extract anywhere, and open `index.html` in any browser — no server required. URLs, navigation, dark mode, and search all work over `file://`.

            **PDF book:** download `twinBASIC Book.pdf` for an offline-readable, printable copy of the full reference.

            Source commit: ${{ github.sha }}.
          files: |
            twinbasic-docs-offline.zip
            twinBASIC Book.pdf
          fail_on_unmatched_files: true
          make_latest: 'true'