docs.yaml

name: Docs

# Only one workflow can run at a time
# If there is newer workflow in progress, cancel older ones
concurrency:
  group: docs
  cancel-in-progress: true

# Put 'on' in quotes to avoid YAML parsing error
"on":
  # Enable manual triggering
  workflow_dispatch: {}
  # Run on commits to main branch
  push:
    branches:
      - main
    # Run only on changes to relevant files
    paths:
      - .github/workflows/docs.yaml
      - docs/**
      - flake.lock
      - "*.nix"
      - Taskfile.dist.yaml

jobs:
  build:
    name: Build docs
    # Pin version of Ubuntu to avoid breaking changes
    runs-on: ubuntu-22.04
    # Use reasonable timeout to avoid stuck workflows
    timeout-minutes: 10
    env:
      NIX_CACHE_DIR: /home/runner/.nixcache/
    permissions:
      # Needed to checkout code
      contents: read
      # Needed to upload page artifact
      pages: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4.1.1
      - name: Setup Nix cache
        uses: actions/cache@v4.0.1
        id: cache-nix
        with:
          path: ${{ env.NIX_CACHE_DIR }}
          key: docs-nix
      - name: Setup docs modules cache
        uses: actions/cache@v4.0.1
        with:
          path: docs/node_modules/
          key: docs-modules
      - name: Install Nix
        uses: cachix/install-nix-action@v26
        with:
          github_access_token: ${{ github.token }}
          install_url: https://releases.nixos.org/nix/nix-2.20.5/install
      # See: https://github.com/cachix/install-nix-action/issues/56
      - name: Import Nix store cache
        if: steps.cache-nix.outputs.cache-hit == 'true'
        run: >
          nix-store
          --import
          < ${{ env.NIX_CACHE_DIR }}/archive.nar
      - name: Build docs
        run: >
          nix
          develop
          ./#docs
          --command
          --
          task
          docs
          --
          build
          --out-dir
          build/
      - name: Setup Pages
        uses: actions/configure-pages@v4.0.0
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3.0.1
        with:
          path: docs/build/
      # See: https://github.com/cachix/install-nix-action/issues/56
      - name: Export Nix store cache
        if: "!cancelled()"
        run: >
          mkdir
          --parents
          ${{ env.NIX_CACHE_DIR }}
          &&
          nix-store
          --export $(find /nix/store/ -maxdepth 1 -name '*-*')
          > ${{ env.NIX_CACHE_DIR }}/archive.nar
  deploy:
    name: Deploy docs
    # Run only if build job succeeded
    needs: build
    # Pin version of Ubuntu to avoid breaking changes
    runs-on: ubuntu-22.04
    # Use reasonable timeout to avoid stuck workflows
    timeout-minutes: 10
    # Use Pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      # Needed to to deploy to Pages
      pages: write
      # Also needed to deploy to Pages
      id-token: write
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4.0.4