pages.yml

name: docs site

on:
  push:
  pull_request:

env:
  CARGO_TERM_COLOR: always
  # Single source of truth for the mdBook version: check-docs-site.sh
  # tells contributors to install the version pinned here. Never
  # install unpinned.
  MDBOOK_VERSION: 0.5.4

permissions:
  contents: read

jobs:
  build:
    name: Build Documentation Site
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: stable
      - name: Install mdBook
        run: cargo install mdbook --version ${{ env.MDBOOK_VERSION }} --locked
      - name: Build and link check
        run: ./scripts/check-docs-site.sh
      - name: Post-process for search and AI-assistant discovery
        run: ./scripts/postprocess-docs-site.sh
      - name: Upload site
        uses: actions/upload-pages-artifact@v5
        with:
          path: site/book
          # mdBook emits site/book/.nojekyll, and v4 started dropping
          # hidden files from the artifact by default.
          include-hidden-files: true

  deploy:
    name: Deploy Documentation Site
    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
    needs: build
    runs-on: ubuntu-latest
    # Publishes the artifact built above and checks nothing out, so it
    # needs no contents scope of its own.
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5