docs.yml

name: Publish Docs

# Publishes the versioned docs site to GitHub Pages.
#
# Discovers the versions to publish from the repository's GitHub releases (the
# latest release, by date, for each major >= 1), builds each selected content ref into
# its own sub-path (e.g. /v1/ and /v2/) with make generate-docs, injects a
# version-picker widget into each page, adds a root redirect to the default
# version, and deploys the combined site. Release and manual triggers use the
# release-tag content by default; manual runs can select latest release branches.
# Orchestration scripts and picker assets always come from current main.
# Triggers on release publish and manual dispatch.

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      docs_source:
        description: Source for every published major-version path
        required: true
        default: release-tags
        type: choice
        options:
        - release-tags
        - latest-branches

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write # Required for actions/deploy-pages

# Allow only one concurrent deployment. Cancel any in-progress run when a newer one
# starts: every run rediscovers the current releases and rebuilds the whole site from
# scratch, so a newer run fully supersedes the work of the one it cancels.
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  publish-docs:
    # Only publish from the modelcontextprotocol/csharp-sdk repository
    if: ${{ github.repository == 'modelcontextprotocol/csharp-sdk' }}
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Checkout docs orchestration
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        # Keep orchestration scripts and picker assets current with main.
        ref: main
        # Full history and tags for immutable content worktrees.
        fetch-depth: 0

    - name: .NET Setup
      uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
      with:
        dotnet-version: |
          10.0.x
          9.0.x

    - name: Test docs orchestration
      run: node --test scripts/docs-branches.test.mjs

    - name: Discover versions from GitHub releases
      shell: bash
      env:
        GH_TOKEN: ${{ github.token }}
      # For every major version >= 1, take the most recently published (by date)
      # non-draft release tagged v{major}.*. The vN prefix becomes the URL slug;
      # the site root redirects to the newest release, including prereleases.
      run: |
        set -euo pipefail
        gh release list --repo "${{ github.repository }}" --limit 200 \
          --json tagName,isPrerelease,isDraft,publishedAt \
          --jq '
            [ .[]
              | select((.isDraft | not) and (.tagName | test("^v[1-9][0-9]*\\.")))
              | { slug: (.tagName | match("^v[0-9]+").string),
                  ref: .tagName, label: .tagName,
                  prerelease: .isPrerelease, published: .publishedAt }
            ]
            | group_by(.slug)
            | map(max_by(.published))
            | sort_by(.published) | reverse
            | { default: .[0].slug,
                versions: map({ slug, ref, label, prerelease }) }
          ' | tee "$RUNNER_TEMP/docs-versions.json"

    - name: Build all versions
      shell: bash
      env:
        DOCS_SOURCE: ${{ inputs.docs_source || 'release-tags' }}
      run: |
        set -euo pipefail
        ROOT="$PWD"
        COMBINED="$ROOT/combined"
        rm -rf "$COMBINED"
        mkdir -p "$COMBINED"

        echo "Docs orchestration: refs/heads/main at $(git rev-parse HEAD)"
        git fetch --tags --prune origin "+refs/heads/*:refs/remotes/origin/*"
        # Resolve and validate every selected content ref once, before building any version.
        # Use a file rather than process substitution so resolution failures stop the run.
        node "$ROOT/scripts/list-versions.mjs" --source "$DOCS_SOURCE" > "$RUNNER_TEMP/docs-sources.tsv"

        while IFS=$'\t' read -r slug ref sha; do
          echo "::group::Build $slug (from $ref at $sha)"
          wt="$ROOT/../work-$slug"
          git worktree add --detach "$wt" "$sha"

          make -C "$wt" generate-docs

          mkdir -p "$COMBINED/$slug"
          cp -a "$wt/artifacts/_site/." "$COMBINED/$slug/"
          node "$ROOT/scripts/inject-version-picker.mjs" "$COMBINED/$slug" "$slug" --base /

          git worktree remove --force "$wt"
          echo "::endgroup::"
        done < "$RUNNER_TEMP/docs-sources.tsv"

        node "$ROOT/scripts/finalize-docs-site.mjs" "$COMBINED"

        echo "Combined site contents:"
        ls -la "$COMBINED"

    - name: Upload Pages artifact
      uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
      with:
        path: 'combined'

    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1