deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

# Allow one deploy at a time; do not cancel an in-flight run so a publish
# that has already reached GitHub Pages can finish cleanly.
concurrency:
  group: pages
  cancel-in-progress: false

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: npm

      - name: Install dependencies
        run: npm ci

      # Restore the upstream-docs cache from the most recent run.
      # The cache is keyed by github.run_id so each run writes a unique key,
      # and restore-keys always restores the most recent prior cache. Combined
      # with the SHA-keyed cache check inside fetch-upstream-docs.cjs, repeat
      # builds skip downloads entirely unless upstream actually changed.
      - name: Restore upstream docs cache
        uses: actions/cache@v4
        with:
          path: .cache/upstream-grobid-doc
          key: upstream-grobid-doc-${{ github.run_id }}
          restore-keys: |
            upstream-grobid-doc-

      # Fetch reference docs from kermitt2/grobid before building. The script
      # fails gracefully (exits 0 with a warning) on network errors, so a
      # GitHub API outage cannot block deploys. GITHUB_TOKEN is auto-provided
      # by Actions and raises the API rate limit from 60/hr to 5000/hr.
      - name: Fetch upstream reference docs
        run: node scripts/fetch-upstream-docs.cjs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Regenerate the LLM index against the freshly fetched cache. We can't
      # rely on `npm run build`'s `prebuild` hook because that also runs
      # generate-docker-configs.cjs which needs a sibling ../grobid-home/
      # checkout that doesn't exist in CI. Calling the LLM index generator
      # directly is the surgical option.
      - name: Regenerate LLM doc index
        run: node scripts/generate-llm-docs-index.cjs

      # Call docusaurus directly rather than `npm run build`: the `prebuild`
      # hook tries to regenerate src/generated/dockerBaseConfigs.ts from a
      # sibling ../grobid-home/ checkout that only exists in local dev
      # environments. The generated TS files are committed to git, so the
      # build has everything it needs without the hook.
      #
      # DOCS_GISCUS_* envs come from repo secrets and enable the Giscus
      # comments widget. The swizzled DocItem/Layout component skips rendering
      # Giscus entirely when these are unset, so deploys without the secrets
      # configured still work — they just don't show comments. To enable
      # comments: install the Giscus GitHub App on this repo, enable repo
      # Discussions, then add DOCS_GISCUS_REPO_ID + DOCS_GISCUS_CATEGORY_ID
      # (and optionally DOCS_GISCUS_CATEGORY) as repo secrets at
      # https://github.com/grobidOrg/grobid-tutorial/settings/secrets/actions
      - name: Build site
        env:
          DOCS_GISCUS_REPO_ID: ${{ secrets.DOCS_GISCUS_REPO_ID }}
          DOCS_GISCUS_CATEGORY_ID: ${{ secrets.DOCS_GISCUS_CATEGORY_ID }}
          DOCS_GISCUS_CATEGORY: ${{ secrets.DOCS_GISCUS_CATEGORY }}
        run: npx docusaurus build

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

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