docs.yml

name: Deploy docs

# Build the mkdocs-material site and deploy to GitHub Pages.
# The CNAME file at the repo root maps the deploy to docs.nullrun.io.
#
# DNS at the registrar (netim.net) must point docs.nullrun.io at GitHub
# Pages. For an apex-style custom domain on a project page, add four A
# records for the `docs` subdomain pointing at the GitHub Pages IPs:
#   185.199.108.153
#   185.199.109.153
#   185.199.110.153
#   185.199.111.153
# …or a single CNAME record pointing docs.nullrun.io at
# nullrunio.github.io. GitHub's docs walk through both options.
#
# Once the workflow is merged and the DNS records land, enable Pages in
# repo Settings → Pages → Source: "GitHub Actions". The first run after
# that will publish the site at https://docs.nullrun.io.

on:
  push:
    branches: [master]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install mkdocs + material theme
        run: |
          python -m pip install --upgrade pip
          pip install \
            mkdocs \
            mkdocs-material \
            pymdown-extensions

      - name: Build site
        run: mkdocs build --strict

      - name: Add CNAME to artifact root
        # mkdocs only copies the `docs/` tree into `site/`, so the
        # CNAME file at the repo root never makes it into the
        # published artifact. Without it, GitHub Pages has no way to
        # know that docs.nullrun.io maps to this repo and returns
        # 404 for every request to the custom domain (the deploy
        # step succeeds, but the published site is unreachable
        # under the canonical URL).
        # Copy it explicitly so /CNAME ends up at site/CNAME in the
        # Pages artifact.
        run: cp CNAME site/CNAME

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4