Skip to content
TheChatArchiveThe Chat Archive
Step 3.5 Flash· unknownHugging Face Frontier Reasoning Traces

Create a docs-as-code pipeline with previews, review gates, and links.

  1. User

    Create a docs-as-code pipeline with previews, review gates, and links.

  2. Assistant

    We are going to set up a docs-as-code pipeline with previews, review gates, and links. Steps:

    1. Set up a repository for documentation (likely in a version control system like Git).
    2. Use a static site generator (like Sphinx, MkDocs, Jekyll, etc.) to generate the documentation from source files (written in Markdown, reStructuredText, etc.).
    3. Set up a continuous integration (CI) pipeline to build the documentation on every commit and push to a preview environment (like a staging site or using a service that provides previews for each pull request).
    4. Implement review gates: require that changes to the documentation are reviewed (via pull/merge requests) and that the build passes before merging.
    5. After merging to the main branch, deploy to the production documentation site.
    6. Ensure that the documentation includes links (internal and external) and that they are validated (broken link checking) as part of the CI process.

    We'll outline a generic pipeline and then give an example using a common stack: GitHub with MkDocs and GitHub Actions.

    Example Stack:

    • Repository: GitHub
    • Static Site Generator: MkDocs (with Material theme)
    • CI/CD: GitHub Actions
    • Preview: Using the mkdocs serve on a GitHub Actions runner and then using a service like https://github.com/JamesIves/github-pages-deploy-action to deploy to a preview environment? Alternatively, use a service that provides PR previews (like Read the Docs for Sphinx, but for MkDocs we can use a similar approach).

    However, note: for previews on PRs, we can set up GitHub Actions to build the site and then deploy it to a temporary location (like an orphan branch or a GitHub Pages branch for previews). But there are also third-party services that can do this.

    Alternatively, we can use a service like Vercel or Netlify that can provide preview URLs for each PR.

    Let's break down:

    1. Repository setup:

      • Create a repository for the documentation.
      • Write documentation in Markdown (for MkDocs) and have an mkdocs.yml configuration file.
    2. CI pipeline (GitHub Actions):

      • On every push and pull request, we want to: a. Check out the code. b. Set up Python (if using MkDocs) and install dependencies (mkdocs and any plugins). c. Build the site (to check for build errors). d. Run a link checker (like markdown-link-check or lychee). e. Deploy to a preview environment for PRs (if it's a PR) and to production for pushes to main.
    3. Review gates:

      • Require that the CI build and link check pass before merging the PR.
      • Require at least one approving review.
    4. Preview environment:

      • For PRs, we can deploy to a unique URL (like https://<pr-number>--<repository>.github.io/ if using GitHub Pages for previews). But note: GitHub Pages doesn't natively support per-PR previews. We can use a separate branch for each PR? That might be messy.

      Alternatively, we can use a service that integrates with GitHub and provides per-PR previews, such as: - Vercel: can deploy each PR to a unique URL. - Netlify: can deploy each PR to a unique URL.

      But if we want to stick with GitHub Actions and GitHub Pages, we can set up two branches for deployments: - gh-pages for production (built from main branch). - For PRs, we can build and then push to a branch named preview-<pr-number> and then use GitHub Pages to serve that branch? But that would require setting up GitHub Pages to use that branch and then having to change the setting for each PR? Not ideal.

      Another idea: use a GitHub Action that deploys to an environment that is accessible via a URL. We can use a static hosting service that supports arbitrary directories or use a storage bucket (like AWS S3, Google Cloud Storage, or Azure Blob Storage) and set up the action to upload the built site to a bucket with a path that includes the PR number. Then we can generate a link and post it as a comment on the PR.

      However, there's a simpler way: use the github-pages-deploy-action to deploy to the gh-pages branch for production, and for PRs, we can use a separate deployment target (like a folder in the same gh-pages branch but under a preview directory) and then use a GitHub Pages site that is configured to serve from that preview directory for PRs? But then we need a way to have two different GitHub Pages sites? Or we can use a custom domain for production and the default GitHub Pages domain for previews? This is getting complicated.

      Let me suggest:

      We can use the following approach for PR previews:

      • Set up a GitHub Action that on PR will:
        1. Build the site.
        2. Use the gsdh/ GitHub Action for deploying to GitHub Pages (or similar) to deploy to a branch that is specific to the PR, and then set the GitHub Pages source for the repository to that branch? But we can only have one source for GitHub Pages.

      Alternatively, we can use a third-party service that provides previews and integrates with GitHub. For example, Read the Docs (for Sphinx) or for MkDocs, we can use the mkdocs-material with a GitHub Action that deploys to a storage bucket and then we use a CDN to serve the previews.

      Given the complexity, maybe we should consider:

      Option 1: Use Netlify or Vercel. They both can automatically create a preview URL for each PR and deploy the static site. Then we just need to set up the build command and output directory.

      Option 2: Use GitHub Pages but with a custom setup:

      We can have two GitHub Pages sites? One for production (from main branch) and one for previews (from a branch that is updated for each PR). But then we need to manage two separate repositories? Or we can use the same repository but two different branches and then set up two separate GitHub Pages sites? That is not possible because one repository can only have one GitHub Pages site.

      So, if we want to use GitHub Pages for both, we might have to:

      • Deploy production to the gh-pages branch (which is the default for GitHub Pages).
      • For PRs, we deploy to a branch named preview-<pr-number> and then we have a separate repository that uses that branch as the source for GitHub Pages? That's too many repos.

      Alternatively, we can use the same gh-pages branch and store each PR preview in a subdirectory (like preview/123 for PR #123). Then we can have a single GitHub Pages site and the preview would be at https://<username>.github.io/<repository>/preview/123/. But then we need to clean up old previews.

      We can do:

      • On PR, build and then push the built site to the gh-pages branch in a directory named preview/<pr-number>.
      • Then we can comment on the PR with the preview URL: https://<username>.github.io/<repository>/preview/<pr-number>/
      • When the PR is closed (merged or not), we can delete that directory.

      But note: if multiple PRs are open, we might have conflicts in the gh-pages branch because each PR push will try to update the same branch. We can avoid this by having a dedicated branch for previews? But then we can't use GitHub Pages to serve that branch because we are using the gh-pages branch for production.

      Wait, we can set up GitHub Pages to use any branch and any folder. So we can have:

      • Production: served from gh-pages branch at the root.
      • Previews: served from a branch named previews at the root? But then we would have to change the GitHub Pages source to that branch for previews? We can't change the source on the fly.

      So, maybe we should use a different hosting for previews? Like an AWS S3 bucket that we can write to arbitrarily.

      Given the complexity, let's go with a third-party service that provides PR previews for static sites, like Vercel or Netlify. They have free tiers and are easy to set up.

      Steps for Vercel:

      • Import the GitHub repository to Vercel.
      • Set the build command to mkdocs build and output directory to site.
      • Vercel will automatically create a preview deployment for each PR and a production deployment for the main branch.

      Then we don't need to handle the preview deployment in our GitHub Actions? But we still want to run the link checks and other CI steps.

      We can have:

      • GitHub Actions for building and testing (including link checks) on every PR and push to main.
      • Vercel for preview and production deployments, but only if the CI passes? We can set up Vercel to require that the GitHub Actions pass? Actually, Vercel will build and deploy on every PR and push, but we can set up Vercel to ignore builds if the commit status from GitHub Actions is failing? Not directly.

      Alternatively, we can have:

      • GitHub Actions run on every PR and push to main, and if the build and link checks pass, then we trigger a Vercel deployment? But Vercel already does that automatically.

      Actually, we can set up Vercel to use the GitHub repository and then it will automatically build and deploy on every push. But we want to run our own CI (with link checks) and then if that passes, then we want to deploy. But if we use Vercel's automatic deployments, then we are building twice? We can disable Vercel's build and use our own? But then we need to deploy to Vercel via API.

      Let's simplify:

      We can have:

      1. GitHub Actions runs on every PR and push to main, and does:
        • Build the site.
        • Run link checks.
        • If it's a PR, then we don't deploy? We just run the checks and then rely on Vercel to provide the preview? But Vercel will build and deploy on its own.

      Alternatively, we can let Vercel handle the build and deploy for previews and production, and then in our GitHub Actions we just run the link checks and other tests, and if they fail, we set the commit status to failing. Then we can set up Vercel to not deploy if the commit status is failing? Vercel has an option to "Ignore build step" but that's for skipping the build, not for failing the deployment.

      Actually, Vercel will deploy regardless of the GitHub commit status. So we need to make sure that the Vercel build fails if our tests fail? But then the preview would be broken.

      Another idea: we can have our GitHub Actions run the build and tests, and then if they pass, we trigger the Vercel deployment via the Vercel API? But then we are building twice.

      Given the complexity, I think the simplest is to let Vercel (or Netlify) handle the build and deploy for previews and production, and then we run our link checks as part of the Vercel build process? We can set up the Vercel build command to be a script that runs the tests and then builds, and if the tests fail, the build fails and Vercel won't deploy.

      But then we are not running the tests on every PR in GitHub Actions? We can set up GitHub Actions to run the tests in parallel to Vercel? That would be two builds.

      Let me re-think:

      We want:

      • Fast feedback on PRs: run tests (build and link checks) and then have a preview if tests pass.
      • We don't want to deploy if tests fail.

      So:

      Option A: - GitHub Actions: run on every PR and push to main, run build and tests (including link checks). If they pass, set a commit status to success. - Vercel: set up to automatically deploy on every PR and push to main, but we can set up Vercel to only deploy if the commit status from GitHub Actions is successful? Vercel doesn't have that feature.

      Option B: - We disable Vercel's automatic deployments and use the Vercel API to deploy only when we want (i.e., when our GitHub Actions pass). But then we are building in GitHub Actions and then deploying the built site to Vercel? That would require us to upload the built site to Vercel.

      Option C: - We let Vercel build and deploy, but we add a step in the Vercel build process (via vercel-build script in package.json or in the Vercel project settings) that runs our tests and then builds. If tests fail, the build fails and Vercel won't deploy.

      This seems the most straightforward. We can have:

      In the repository, we have a package.json (even if we don't use Node) to define a script:

      {
        "scripts": {
          "vercel-build": "mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'"
        }
      }
      

      But note: Vercel by default will run npm run build if it finds a package.json. So we can set the build command in Vercel to npm run vercel-build? Actually, Vercel will run npm run build by default. So we can set our tests and build in the build script.

      However, we want the build to fail if the link checks fail. So we can do:

      "scripts": {
        "build": "mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'"
      }
      

      Then Vercel will run npm run build and if either the build or the link check fails, the Vercel build fails and it won't deploy.

      But note: the link check might fail for external links that are down, which we might not want to block the deployment. We can adjust the link check to ignore certain links or have a tolerance.

      Alternatively, we can run the link check as a separate step in GitHub Actions and then have Vercel only deploy if the GitHub Actions pass? But again, Vercel doesn't check the GitHub status.

      Given the time, let's go with:

      • Use Vercel for hosting and previews.
      • Set up Vercel to build the site and run the link check as part of the build. If the build (including link check) fails, Vercel won't deploy.
      • Also set up GitHub Actions to run the same build and link check on every PR and push to main, so we have the status in GitHub.

      But then we are building twice? We can choose one. Since Vercel will build on every PR and push, we can rely on Vercel for the build and then in GitHub Actions we just run the same tests? That's duplicate.

      Alternatively, we can have GitHub Actions run the tests and then if they pass, we let Vercel deploy? But Vercel will build again.

      We can have:

      GitHub Actions: on: [pull_request, push] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md'

      Then we set up Vercel to automatically deploy on every PR and push, but we don't run the tests in Vercel? Then we have a situation where the Vercel preview might be deployed even if the tests fail in GitHub Actions? That's not good.

      So we need to prevent Vercel from deploying if the GitHub Actions tests fail.

      We can set up Vercel to use the GitHub Checks API? Vercel doesn't support that natively.

      Another idea: use the Vercel GitHub App and set up branch protection that requires the Vercel deployment to be successful? But Vercel doesn't set a commit status.

      Given the complexity, I think we should:

      • Use GitHub Actions to run the tests and build, and then if they pass, we deploy to Vercel using the Vercel API.

      Steps:

      1. GitHub Actions runs on PR and main push.
      2. On PR, we run the tests and build. If they pass, we don't deploy (preview will be handled by Vercel automatically? but we disabled automatic deployments).
      3. On push to main, if tests pass, we deploy to Vercel production.

      But then what about PR previews? We want previews for PRs. So we need to deploy on PRs too.

      So:

      • We set up Vercel to not automatically deploy (disable automatic deployments in Vercel).
      • We use GitHub Actions to build and then deploy to Vercel for every PR and for main.

      How to deploy to Vercel from GitHub Actions?

      We can use the Vercel CLI and the Vercel token.

      Steps:

      • In the GitHub repository, set secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.
      • In the GitHub Actions workflow, after building and testing, we use the Vercel CLI to deploy.

      But note: Vercel will create a new deployment for each PR and for main.

      We can use the amondnet/vercel-action GitHub Action.

      Example workflow:

      name: Deploy to Vercel

      on: pull_request: branches: [ main ] push: branches: [ main ]

      jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md' - name: Deploy to Vercel uses: amondnet/vercel-action@v20 with: vercel-token: secrets.VERCELTOKENvercel−org−id:{{ secrets.VERCEL_TOKEN }} vercel-org-id: {{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} # For PRs, Vercel will create a preview deployment. # For main, it will create a production deployment. # The action automatically determines the environment based on the branch.

      But note: the Vercel action will also build the project? We already built it. We can set the vercel-build-command to npm run build? But we are using Python. We can set the build command to mkdocs build and then we are building twice? We can skip the build in the Vercel action by setting vercel-build-command to something that doesn't build? Or we can set the Vercel project to use our build command? Actually, the Vercel action will run the build command configured in the Vercel project.

      We can set the Vercel project's build command to mkdocs build and then we don't need to run the build in our GitHub Actions? But then we are not running the link check in the Vercel build? We can set the build command to run both:

      mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'
      

      But then if the link check fails, the build fails and Vercel won't deploy.

      Alternatively, we can run the build and tests in GitHub Actions and then if they pass, we let Vercel deploy without building? But Vercel will build by default.

      We can set the Vercel project to have no build command? Then we can build in GitHub Actions and then deploy the built site? But Vercel expects to build.

      Actually, the Vercel action has an option working-directory and output-directory to specify the built files. We can build in GitHub Actions and then tell Vercel to deploy the built files without building again.

      But note: Vercel is designed to build from source. If we pre-build, we can set the project to use a static output? We can set the output directory to site (which is the default for MkDocs). And then in the Vercel project, set the build command to echo " Skipping build" or something? But then we are not running the link check in Vercel.

      Given the complexity, let's simplify:

      We'll run the build and tests in GitHub Actions, and then if they pass, we deploy to Vercel using the Vercel action, but we set the Vercel project to not build (by setting the build command to echo "Skipping build"). Then we set the output-directory in the Vercel action to site (the built directory).

      Steps:

      1. In Vercel project settings, set the build command to echo "Skipping build" and the output directory to site.
      2. In GitHub Actions, we build the site to site and run the link check.
      3. Then we use the Vercel action to deploy the site directory.

      But note: the Vercel action expects to build by default. We can set vercel-build-command to echo "Skipping build" in the action? Actually, the action uses the project settings by default.

      Alternatively, we can set the Vercel project to have a build command of mkdocs build and then we don't build in GitHub Actions? But then we are not running the link check in the same step? We can set the Vercel build command to:

      mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'
      

      Then if the link check fails, the Vercel build fails and it won't deploy.

      But then we are not running the tests in GitHub Actions? We want the status in GitHub.

      We can do:

      GitHub Actions runs the tests and build. Then we deploy to Vercel, which runs the same build and tests again? That's duplicate.
      

      Given the time, I think the best is:

      Let Vercel handle the build and tests (by setting the build command to run both). Then in GitHub Actions, we just run the same build and tests to set the commit status? But then we are building twice.
      

      Alternatively, we can have:

      GitHub Actions runs the tests and build. Then if they pass, we set a commit status to success. Then we use the Vercel action to deploy, but we tell Vercel not to build (by setting the build command to `echo "Skipping build"`). Then we deploy the pre-built site.
      

      This way, we only build once (in GitHub Actions) and we get the commit status.

      Steps:

      In Vercel project settings: Build command: echo "Skipping build" Output directory: site

      In GitHub Actions:

      - Build the site to `site`
      - Run link check (if fails, the job fails)
      - Then deploy the `site` directory to Vercel.
      

      But note: the link check might require the built site? Actually, the link check should run on the source markdown. We are currently running it on the source. But if we set the build command in Vercel to skip, we don't run the link check in Vercel.

      So we run the link check in GitHub Actions, and if it fails, we don't deploy.

      This seems good.

      However, note: the link check might break due to the way the built site has different URLs? We are checking the markdown files, which have relative links. That should be okay.

      Let's write the GitHub Actions workflow:

      We'll have:

      name: Build and Deploy
      
      on:
        pull_request:
          branches: [ main ]
        push:
          branches: [ main ]
      
      jobs:
        build-and-deploy:
          runs-on: ubuntu-latest
          steps:
            - name: Checkout
              uses: actions/checkout@v3
      
            - name: Setup Python
              uses: actions/setup-python@v4
              with:
                python-version: '3.x'
      
            - name: Install dependencies
              run: |
                pip install mkdocs
                pip install markdown-link-check
      
            - name: Build
              run: mkdocs build --strict
      
            - name: Link check
              run: markdown-link-check --config .markdown-link-check.json '**/*.md'
      
            - name: Deploy to Vercel
              uses: amondnet/vercel-action@v20
              with:
                vercel-token: ${{ secrets.VERCEL_TOKEN }}
                vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
                vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
                # We are deploying the pre-built `site` directory.
                # The Vercel project is set to not build and to use the `site` directory as output.
                # So we don't need to set the build command here.
      

      But note: the Vercel action by default will run the build command set in the Vercel project. We set that to echo "Skipping build", so it won't build again.

      However, we are building in the GitHub Actions and then the Vercel action will upload the site directory? Actually, the Vercel action will run the build command (which we set to skip) and then upload the output directory (which we set to site). But we built the site in the GitHub Actions runner, so the site directory exists. Then the Vercel action will run echo "Skipping build" and then upload the site directory.

      But wait: the Vercel action might run in a different working directory? We are building in the root of the repository, and the site directory is at the root. The Vercel action by default uses the current directory. So it should work.

      However, note: the Vercel action might run in a subdirectory? We can set working-directory if needed.

      But there's a catch: the Vercel action might clean the directory? We are building and then the Vercel action runs in the same directory, so the site directory is there.

      This should work.

      But what about the link check configuration? We have a .markdown-link-check.json file. We need to include that in the repository.

      Example .markdown-link-check.json:

      {
        "ignorePatterns": [
          {
            "pattern": "^https://example\\.com/.*"
          }
        ],
        "timeout": "10s",
        "retryCount": 3
      }
      

      We can adjust as needed.

    5. Review gates:

      In GitHub, we set up branch protection for the main branch: - Require pull request reviews (at least one). - Require status checks to pass (the GitHub Actions workflow).

    6. Links:

      We are already checking links with markdown-link-check. We can also use other tools like lychee if we prefer.

      We might also want to check for broken internal links (to other pages in the site). The mkdocs build might fail if there are broken internal links? By default, MkDocs doesn't fail on broken internal links, but we can use the --strict flag to fail on warnings.

      Alternatively, we can use the mkdocs-exclude plugin or other plugins to help.

      But note: the --strict flag in MkDocs will fail on warnings, which includes broken internal links (if using nav that points to non-existing files). So that should catch internal broken links.

    7. Summary:

      • Repository with MkDocs and markdown files.

      • GitHub Actions workflow that: a. Checks out code. b. Sets up Python and installs MkDocs and markdown-link-check. c. Builds the site with mkdocs build --strict (fails on warnings). d. Runs markdown-link-check on all markdown files. e. If both steps pass, deploys to Vercel (which is set up to skip building and just deploy the pre-built site directory).

      • Vercel project:

        • Build command: echo "Skipping build"
        • Output directory: site
        • Set up the repository and connect it.
      • In GitHub, set up branch protection on main to require:

        • At least one review.
        • The GitHub Actions workflow to pass.

      This gives us: - Previews: Vercel creates a preview for every PR and for main (production). - Review gates: PRs require review and passing CI. - Links: checked in the CI.

      However, note: the link check runs on the source markdown, so it might not catch broken links that are only in the built HTML? Actually, the markdown-link-check checks the links in the markdown, which are the same as in the built HTML (for relative links). For absolute links, it will check the target. So it should be fine.

      But what about internal anchors? The link check might not handle them well. We can configure the link checker to ignore fragments? Or we can use a different tool.

      Alternatively, we can use lychee which can check links in the built HTML? We can run lychee on the built HTML files.

      We can adjust:

      - Build the site.
      - Run `lychee` on the `site` directory (the built HTML) to check all links (including internal ones).
      

      But note: lychee might be slower.

      We can stick with markdown-link-check for now and adjust the configuration to ignore fragments if needed.

      Example configuration to ignore fragments:

      {
        "ignorePatterns": [
          {
            "pattern": ".*#.*"
          }
        ]
      }
      

      But that would ignore all links with fragments, which might be too broad.

      Alternatively, we can use markdown-link-check with the --ignorePattern flag? The configuration file supports ignorePatterns.

      We can also use the --no-ansi flag to avoid output issues.

      Given the complexity of link checking, we might want to use a combination of tools.

      But for simplicity, we'll use markdown-link-check on the markdown files and rely on mkdocs build --strict for internal link checks (for the navigation structure).

      Let's adjust the workflow to run markdown-link-check on the markdown files and then mkdocs build --strict (which will check the internal links in the navigation). Actually, mkdocs build --strict will fail on warnings, which includes unresolved references in the navigation. So that should catch internal broken links.

      So we are covered.

      Let's write the workflow file:

      File: .github/workflows/build-and-deploy.yml

      We'll also add a step to set up the Vercel project? We already have the secrets.

      But note: the Vercel action requires the project to be already set up in Vercel. We have to create the project in Vercel and link it to the GitHub repository.

      Steps:

      1. Create a Vercel account and import the GitHub repository.
      2. In Vercel project settings, set:
        • Build command: echo "Skipping build"
        • Output directory: site
      3. Get the VERCEL_ORG_ID and VERCEL_PROJECT_ID from the Vercel project settings (in the project, go to Settings -> General -> Project ID and Organization ID).
      4. Generate a Vercel token (from Vercel account settings -> Tokens).
      5. Add the following secrets in the GitHub repository (Settings -> Secrets and variables -> Actions):
        • VERCEL_TOKEN
        • VERCEL_ORG_ID
        • VERCEL_PROJECT_ID

      Then the workflow should work.

      Let's write the workflow:

      Note: We are building and then deploying. We want to deploy only if the build and link check pass.

      We'll also add a step to show the preview URL in the PR? The Vercel action will output the URL. We can capture it and then comment on the PR? But the Vercel action doesn't output the URL in a way that we can capture easily? Actually, the Vercel action outputs the deployment URL. We can set an output and then use a separate step to comment.

      But the Vercel action already comments on the PR? Actually, the Vercel GitHub App does that automatically if we have it installed? The Vercel action does not comment by default.

      We can use the actions/github-script to comment on the PR with the preview URL.

      But note: the Vercel action will output the deployment URL as an output. We can capture it and then comment.

      However, for PRs, we want the preview URL. For main, we don't need to comment.

      We can do:

      - name: Deploy to Vercel
        id: vercel
        uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
      
      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const url = '${{ steps.vercel.outputs.preview-url }}'
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview deployment: ${url}`
            })
      

      But note: the Vercel action outputs preview-url for preview deployments and production-url for production. We can check which one we got? Actually, the action sets:

      outputs:
        preview-url: ${{ steps.vercel.outputs.preview-url }}
        production-url: ${{ steps.vercel.outputs.production-url }}
      

      And we are only interested in the preview-url for PRs.

      However, the Vercel action might set both? Let's check the documentation.

      Actually, the action sets:

      - For preview deployments (on PRs and non-main branches): `preview-url`
      - For production deployments (on main): `production-url`
      

      So we can use:

      if: github.event_name == 'pull_request'
      then use steps.vercel.outputs.preview-url
      

      But note: the action might set both? We can use:

      url: ${{ steps.vercel.outputs.preview-url || steps.vercel.outputs.production-url }}
      

      But for PRs, we want the preview-url, and for main, we don't comment.

      Alternatively, we can conditionally set the URL:

      - name: Set URL
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            echo "url=${{ steps.vercel.outputs.preview-url }}" >> $GITHUB_OUTPUT
          fi
        id: set-url
      
      Then use ${{ steps.set-url.outputs.url }} in the comment.
      

      But the Vercel action might not set preview-url for production deployments? So for PRs, we expect preview-url to be set.

      Let's adjust:

      - name: Deploy to Vercel
        id: vercel
        uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
      
      - name: Comment on PR
        if: github.event_name == 'pull_request' && steps.vercel.outputs.preview-url != ''
        uses: actions/github-script@v6
        with:
          script: |
            const url = '${{ steps.vercel.outputs.preview-url }}'
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview deployment: ${url}`
            })
      

      But note: the Vercel action might take a while to deploy. We want to comment only after deployment is done. The amondnet/vercel-action waits until the deployment is finished? Yes, by default it waits.

      However, if the deployment fails, we don't want to comment? The step would fail and the workflow would stop, so we wouldn't comment.

      This should work.

      Let's put it all together.

      However, note: the Vercel action might fail if the build command (which we set to echo "Skipping build") returns non-zero? We set it to echo which returns 0.

      But wait: we are building in the GitHub Actions, so the site directory exists. Then the Vercel action runs echo "Skipping build" and then uploads the site directory.

      But what if the Vercel action expects the build to have been run by the build command? It doesn't, because we set the output directory to site and we are uploading that directory.

      However, the Vercel action might run the build command and then expect the output in the output directory. If we skip the build, then the output directory might not have been created? Actually, we built it in a previous step, so the site directory exists.

      This should be okay.

      But note: the Vercel action might clean the working directory? I don't think so.

      Alternatively, we can use the Vercel action without a build command? Actually, the Vercel project must have a build command set. We set it to echo "Skipping build" so it does nothing.

      Let's write the full workflow:

      We'll also add a step to cache the Python dependencies to speed up.

      Final workflow:

      .github/workflows/build-and-deploy.yml:

      name: Build and Deploy
      
      on:
        pull_request:
          branches: [ main ]
        push:
          branches: [ main ]
      
      jobs:
        build-and-deploy:
          runs-on: ubuntu-latest
          steps:
            - name: Checkout
              uses: actions/checkout@v3
      
            - name: Setup Python
              uses: actions/setup-python@v4
              with:
                python-version: '3.x'
      
            - name: Cache pip
              uses: actions/cache@v3
              with:
                path: ~/.cache/pip
                key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/setup.py', '**/pyproject.toml') }}
                restore-keys: |
                  ${{ runner.os }}-pip-
      
            - name: Install dependencies
              run: |
                pip install mkdocs
                pip install markdown-link-check
      
            - name: Build
              run: mkdocs build --strict
      
            - name: Link check
              run: markdown-link-check --config .markdown-link-check.json '**/*.md'
      
            - name: Deploy to Vercel
              id: vercel
              uses: amondnet/vercel-action@v20
              with:
                vercel-token: ${{ secrets.VERCEL_TOKEN }}
                vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
                vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
      
            - name: Comment on PR
              if: github.event_name == 'pull_request' && steps.vercel.outputs.preview-url != ''
              uses: actions/github-script@v6
              with:
                script: |
                  const url = '${{ steps.vercel.outputs.preview-url }}'
                  github.rest.issues.createComment({
                    issue_number: context.issue.number,
                    owner: context.repo.owner,
                    repo: context.repo.repo,
                    body: `Preview deployment: ${url}`
                  })
      

      But note: the markdown-link-check might fail for links that are in the site directory (the built HTML) but not in the markdown? We are checking the markdown, so that's okay.

      However, what about links that are generated by plugins? They might not be in the markdown. Then we would miss them.

      We can also run markdown-link-check on the built HTML? But then we would have to adjust the configuration to handle HTML.

      Alternatively, we can use lychee which can check HTML files.

      We can change the link check step to:

      - name: Link check
        run: |
          # Check markdown files
          markdown-link-check --config .markdown-link-check.json '**/*.md'
          # Check built HTML files
          lychee --config .lychee.toml 'site/**/*.html'
      

      But then we need a lychee.toml configuration.

      Given the complexity, let's stick to checking the markdown files and rely on mkdocs build --strict for internal links.

      But note: mkdocs build --strict will fail on warnings, which includes broken internal links (if the navigation points to a non-existing file). However, it might not catch broken links in the content (like [link](nonexistent.md)). Actually, MkDocs will generate a warning for that and with --strict it will fail.

      So we are covered for internal links.

      For external links, we are checking with markdown-link-check.

      This should be acceptable.

      Let's adjust the workflow to also check the built HTML with lychee? We can do:

      - name: Install lychee
        run: cargo install lychee
      

      But that requires Rust, which might be heavy.

      Alternatively, we can use a packaged lychee? There isn't a pre-built one for Ubuntu in the same way.

      Given the time, we'll stick to markdown-link-check on markdown and mkdocs build --strict for internal.

      We can adjust the markdown-link-check configuration to ignore external links that are known to be down? We can set a timeout and retry count.

      Example .markdown-link-check.json:

      {
        "timeout": "10s",
        "retryCount": 3,
        "ignorePatterns": [
          {
            "pattern": ".*#.*"
          }
        ]
      }
      

      This will ignore links with fragments (like #section). We might want to allow fragments? Actually, markdown-link-check by default will try to check the fragment? It will check the URL without the fragment and then the fragment is ignored? Actually, it will fail if the URL without the fragment is down? But if the page exists but the fragment doesn't, it will still pass? Not sure.

      We can leave the configuration as is and adjust if needed.

      This is a reasonable setup.

      Let's summarize the steps for the user:

      1. Set up a repository with MkDocs documentation.
      2. Create a .markdown-link-check.json file for link checking configuration.
      3. Set up Vercel project:
        • Import the GitHub repository.
        • Set build command to echo "Skipping build" and output directory to site.
        • Get the project ID and org ID from Vercel project settings.
        • Generate a Vercel token.
      4. In the GitHub repository, set the secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.
      5. Create the GitHub Actions workflow file at .github/workflows/build-and-deploy.yml with the content above.
      6. Set up branch protection on the main branch to require:
        • At least one review.
        • The GitHub Actions workflow to pass.

      Then:

      • On every PR, the workflow will build, run link checks, and if they pass, deploy to Vercel (preview deployment) and comment on the PR with the preview URL.
      • On push to main, the workflow will build, run link checks, and if they pass, deploy to Vercel (production).

      This gives us: - Previews for PRs. - Review gates (PR review and CI). - Link checking.

      Note: The preview URL for PRs will be something like https://<project-name>.vercel.app/pull/<pr-number>? Actually, Vercel creates a unique URL for each deployment. We are using the Vercel action which will output the preview URL.

      We are done.

      However, note: the Vercel action might not set the preview-url output for production deployments? We are only using it for PRs.

      Let me check the Vercel action documentation: https://github.com/amondnet/vercel-action

      It says:

      outputs:
        preview-url: The URL of the preview deployment
        production-url: The URL of the production deployment
      

      So for PRs, we get preview-url, for main we get production-url.

      We are using preview-url only for PRs.

      This should work.

      Let me adjust the workflow to also set the commit status? The GitHub Actions will set the status automatically (if the job fails, the check fails). So we don't need extra steps.

      We are good.

      One more thing: the Vercel action might require the Vercel CLI to be installed? It uses the Vercel CLI under the hood? It uses the Vercel API? Actually, the action uses the Vercel CLI? The action's Docker image includes the Vercel CLI.

      So we don't need to install it.

      We are set.

      Let me write the final workflow with a few adjustments:

      • We'll use the actions/cache for pip to speed up.
      • We'll use the --strict flag for mkdocs build to fail on warnings.

      But note: the --strict flag might be too strict? We can start without it and then adjust.

      We'll keep it.

      Final workflow:

      .github/workflows/build-and-deploy.yml:

      name: Build and Deploy
      
      on:
        pull_request:
          branches: [ main ]
        push:
          branches: [ main ]
      
      jobs:
        build-and-deploy:
          runs-on: ubuntu-latest
          steps:
            - name: Checkout
              uses: actions/checkout@v3
      
            - name: Setup Python
              uses: actions/setup-python@v4
              with:
                python-version: '3.x'
      
            - name: Cache pip
              uses: actions/cache@v3
              with:
                path: ~/.cache/pip
                key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/setup.py', '**/pyproject.toml') }}
                restore-keys: |
                  ${{ runner.os }}-pip-
      
            - name: Install dependencies
              run: |
                pip install mkdocs
                pip install markdown-link-check
      
            - name: Build
              run: mkdocs build --strict
      
            - name: Link check
              run: markdown-link-check --config .markdown-link-check.json '**/*.md'
      
            - name: Deploy to Vercel
              id: vercel
              uses: amondnet/vercel-action@v20
              with:
                vercel-token: ${{ secrets.VERCEL_TOKEN }}
                vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
                vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
      
            - name: Comment on PR
              if: github.event_name == 'pull_request' && steps.vercel.outputs.preview-url != ''
              uses: actions/github-script@v6
              with:
                script: |
                  const url = '${{ steps.vercel.outputs.preview-url }}'
                  github.rest.issues.createComment({
                    issue_number: context.issue.number,
                    owner: context.repo.owner,
                    repo: context.repo.repo,
                    body: `Preview deployment: ${url}`
                  })
      

      This should work.

      However, note: the Vercel action might fail if the project is not set up correctly. We have set the Vercel project to skip building, so it should just upload the site directory.

      But wait: the Vercel action by default will run the build command set in the Vercel project. We set that to echo "Skipping build". Then it will upload the output directory (which we set to site). But note: the output directory is relative to the project root. Our site directory is at the root, so that's fine.

      We are done.

      Let me know if you have any questions. I'll help you create a comprehensive docs-as-code pipeline with all the features you requested. Here's a complete implementation using modern tools:

    Architecture Overview

    ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
    │   Git Repository│────▶│   CI/CD Pipeline │────▶│ Preview Service│
    │   (Docs Source) │    │   (GitHub Actions)│    │  (Vercel/Netlify)│
    └─────────────────┘    └──────────────────┘    └─────────────────┘
             │                       │                        │
             ▼                       ▼                        ▼
    ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
    │  Review Gates   │◀───│  Link Validation │────│  Production Site│
    │  (PR/MR Checks) │    │  & Quality Gates │    │  (GitHub Pages)│
    └─────────────────┘    └──────────────────┘    └─────────────────┘
    

    Implementation

    1. Repository Structure

    docs-repo/
    ├── docs/
    │   ├── index.md          # Homepage
    │   ├── getting-started/
    │   │   ├── installation.md
    │   │   └── quickstart.md
    │   ├── api/
    │   │   ├── overview.md
    │   │   └── endpoints.md
    │   ├── guides/
    │   └── images/           # Static assets
    ├── mkdocs.yml            # MkDocs configuration
    ├── .github/
    │   ├── workflows/
    │   │   ├── preview.yml   # PR preview deployments
    │   │   ├── link-check.yml # Link validation
    │   │   └── deploy.yml    # Production deployment
    ├── .markdown-link-check.json
    ├── requirements.txt      # Python dependencies
    └── README.md
    

    2. Core Configuration Files

    mkdocs.yml - Main documentation configuration:

    site_name: My Documentation
    site_description: Comprehensive API documentation
    theme:
      name: material
      features:
        - navigation.tabs
        - navigation.sections
        - toc.integrate
        - search.suggest
        - search.highlight
    plugins:
      - search
      - awesome-pages
      - macros:
          # Define variables for reuse
          api_version: v1.2.0
          base_url: https://api.example.com
    nav:
      - Home: index.md
      - Getting Started:
        - Installation: getting-started/installation.md
        - Quickstart: getting-started/quickstart.md
      - API Reference:
        - Overview: api/overview.md
        - Endpoints: api/endpoints.md
      - Guides: guides/
    

    .markdown-link-check.json - Link validation config:

    {
      "ignorePatterns": [
        {
          "pattern": "^https://localhost.*"
        },
        {
          "pattern": "^http://127.0.0.1.*"
        }
      ],
      "timeout": "10s",
      "retryCount": 3,
      "thresholdPer_link": 3,
      "fallbackHttpStatus": [403, 404]
    }
    

    3. GitHub Actions Workflows

    preview.yml - PR preview deployments:

    name: Deploy Preview
    
    on:
      pull_request:
        branches: [main]
        paths:
          - 'docs/**'
          - 'mkdocs.yml'
          - '.github/workflows/preview.yml'
    
    jobs:
      deploy-preview:
        runs-on: ubuntu-latest
        permissions:
          contents: read
          pull-requests: write
          id-token: write
        
        steps:
          - name: Checkout
            uses: actions/checkout@v4
            with:
              fetch-depth: 0
    
          - name: Setup Python
            uses: actions/setup-python@v4
            with:
              python-version: '3.11'
    
          - name: Install dependencies
            run: |
              pip install mkdocs-material
              pip install mkdocs-macros-plugin
              pip install markdown-link-check
    
          - name: Build docs
            run: mkdocs build --strict
    
          - name: Link Check
            run: |
              markdown-link-check --config .markdown-link-check.json "docs/**/*.md"
    
          - name: Deploy to Vercel (Preview)
            uses: amondnet/vercel-action@v20
            with:
              vercel-token: ${{ secrets.VERCEL_TOKEN }}
              vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
              vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
              working-directory: ./site
              vercel-args: '--prebuilt'
    
          - name: Comment preview URL
            if: always()
            uses: actions/github-script@v7
            with:
              script: |
                const previewUrl = process.env.VERCEL_PREVIEW_URL
                if (previewUrl) {
                  github.rest.issues.createComment({
                    issue_number: context.issue.number,
                    owner: context.repo.owner,
                    repo: context.repo.repo,
                    body: `🚀 Preview deployed at ${previewUrl}`
                  })
                }
    

    link-check.yml - Dedicated link validation:

    name: Link Check
    
    on:
      schedule:
        - cron: '0 0 * * *'  # Daily at midnight
      push:
        branches: [main]
        paths:
          - 'docs/**'
          - '.markdown-link-check.json'
    
    jobs:
      check-links:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
    
          - name: Setup Python
            uses: actions/setup-python@v4
            with:
              python-version: '3.11'
    
          - name: Install dependencies
            run: pip install markdown-link-check
    
          - name: Check links
            run: |
              markdown-link-check \
                --config .markdown-link-check.json \
                --quiet \
                "docs/**/*.md" || {
                echo "❌ Broken links found!"
                exit 1
              }
    
          - name: Check for circular references
            run: |
              # Custom script to check for circular refs in nav
              python scripts/check_circular_refs.py docs/
    

    deploy.yml - Production deployment:

    name: Deploy to Production
    
    on:
      push:
        branches: [main]
        paths:
          - 'docs/**'
          - 'mkdocs.yml'
    
    jobs:
      deploy:
        runs-on: ubuntu-latest
        permissions:
          contents: read
          pages: write
          id-token: write
        
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
    
        steps:
          - name: Checkout
            uses: actions/checkout@v4
    
          - name: Setup Python
            uses: actions/setup-python@v4
            with:
              python-version: '3.11'
    
          - name: Install dependencies
            run: |
              pip install mkdocs-material
              pip install mkdocs-macros-plugin
    
          - name: Build
            run: mkdocs build --strict --dirty
    
          - name: Setup Pages
            uses: actions/configure-pages@v3
    
          - name: Upload artifact
            uses: actions/upload-pages-artifact@v2
            with:
              path: './site'
    
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v2
    

    4. Review Gates Implementation

    Branch Protection Rules (GitHub):

    1. Require pull request reviews:

      • At least 1 approving review
      • Dismiss stale PR approvals when new commits are pushed
      • Require review from code owners (if using CODEOWNERS)
    2. Require status checks to pass:

      • Deploy Preview (from preview.yml)
      • Link Check (from link-check.yml)
      • Build (implicit from preview.yml)
    3. Restrict pushes:

      • No direct pushes to main
      • Required linear history

    CODEOWNERS (optional):

    # Docs ownership
    /docs/ @docs-team @technical-writers
    

    5. Quality Gates Scripts

    scripts/check_circular_refs.py - Prevent circular navigation:

    #!/usr/bin/env python3
    """Check for circular references in MkDocs navigation."""
    
    import sys
    import yaml
    from pathlib import Path
    
    def load_nav_structure(nav_file):
        """Load navigation structure from mkdocs.yml."""
        with open(nav_file) as f:
            config = yaml.safe_load(f)
        return config.get('nav', [])
    
    def check_circular_refs(nav, path='', visited=None):
        """Recursively check for circular references."""
        if visited is None:
            visited = set()
        
        current_path = path or 'root'
        if current_path in visited:
            print(f"❌ Circular reference detected at: {current_path}")
            return True
        
        visited.add(current_path)
        
        if isinstance(nav, list):
            for item in nav:
                if isinstance(item, dict):
                    for key, value in item.items():
                        if isinstance(value, (list, dict)):
                            if check_circular_refs(value, key, visited.copy()):
                                return True
        elif isinstance(nav, dict):
            for key, value in nav.items():
                if isinstance(value, (list, dict)):
                    if check_circular_refs(value, key, visited.copy()):
                        return True
        
        return False
    
    if __name__ == "__main__":
        mkdocs_yml = Path('mkdocs.yml')
        if not mkdocs_yml.exists():
            print("❌ mkdocs.yml not found!")
            sys.exit(1)
        
        nav = load_nav_structure(mkdocs_yml)
        if check_circular_refs(nav):
            print("❌ Navigation contains circular references!")
            sys.exit(1)
        
        print("✅ No circular references found")
        sys.exit(0)
    

    6. Additional Utilities

    scripts/generate_toc.py - Auto-generate table of contents:

    #!/usr/bin/env python3
    """Generate table of contents for markdown files."""
    
    import re
    from pathlib import Path
    
    def generate_toc(md_file):
        """Generate TOC from markdown headings."""
        toc = ["## Table of Contents\n"]
        
        with open(md_file) as f:
            for line in f:
                match = re.match(r'^(#{1,6})\s+(.+)$', line)
                if match:
                    level = len(match.group(1))
                    title = match.group(2)
                    indent = '  ' * (level - 1)
                    anchor = title.lower().replace(' ', '-').replace('.', '')
                    toc.append(f"{indent}- [{title}](#{anchor})")
        
        return '\n'.join(toc)
    
    if __name__ == "__main__":
        for md_file in Path('docs').rglob('*.md'):
            print(f"Processing {md_file}...")
            # Insert TOC after first heading
            # Implementation depends on your preference
    

    7. Setup Instructions

    # 1. Initialize the repository
    mkdir docs-repo && cd docs-repo
    git init
    
    # 2. Install dependencies
    pip install mkdocs-material mkdocs-macros-plugin markdown-link-check
    
    # 3. Create configuration files (from above)
    
    # 4. Set up GitHub Secrets:
    #    VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID
    #    (for preview deployments)
    
    # 5. Enable GitHub Pages in repo settings:
    #    Source: GitHub Actions
    
    # 6. Push to GitHub and set up branch protection rules
    

    8. Advanced Features

    mkdocs.yml with macros for dynamic content:

    plugins:
      - macros:
          module_name: docs/macros.py  # Python file with custom macros
          # Example macro usage in markdown: {{ api_base_url() }}
    

    docs/macros.py:

    def api_base_url():
        """Return API base URL based on environment."""
        import os
        env = os.getenv('DOCS_ENV', 'production')
        if env == 'preview':
            return 'https://api-staging.example.com'
        return 'https://api.example.com'
    

    9. Monitoring & Alerts

    Add to link-check.yml for notifications:

    - name: Send Slack notification on failure
      if: failure()
      uses: slackapi/slack-github-action@v1
      with:
        payload: |
          {
            "text": "❌ Link check failed for ${{ github.repository }}",
            "attachments": [
              {
                "color": "danger",
                "fields": [
                  {
                    "title": "PR/Commit",
                    "value": "${{ github.event.pull_request.html_url || github.event.head_commit.url }}",
                    "short": true
                  },
                  {
                    "title": "Author",
                    "value": "${{ github.actor }}",
                    "short": true
                  }
                ]
              }
            ]
          }
      env:
        SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
    

    10. Docker Support (Optional)

    Dockerfile:

    FROM python:3.11-slim
    
    WORKDIR /docs
    
    COPY requirements.txt .
    RUN pip install --no-cache-dir -r requirements.txt
    
    COPY . .
    
    EXPOSE 8000
    CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]
    

    Key Features Implemented:

    ✅ Previews: Vercel automatically creates preview URLs for every PR
    ✅ Review Gates:

    • Branch protection requiring PR approvals
    • CI status checks before merge
    • Link validation as required check

    ✅ Links:

    • Automated link checking (external links)
    • Internal navigation validation via mkdocs build --strict
    • Circular reference detection

    ✅ Quality Gates:

    • Build must succeed
    • No broken links
    • No circular nav references
    • Strict markdown linting (via --strict)

    ✅ Traceability:

    • Preview URLs automatically commented on PRs
    • Deployments tracked in GitHub Environments
    • Full audit trail via Git history

    Usage Workflow:

    1. Developer creates PR → Preview auto-deploys, comment with URL
    2. Reviewer checks preview → Verifies content/layout
    3. CI runs all checks → Fails if broken links or build errors
    4. PR approved and merged → Auto-deploys to production
    5. Daily link check → cron job validates all external links

    This setup provides a robust docs-as-code pipeline with enterprise-grade quality gates, automated previews, and comprehensive link validation. You can adapt it to use Sphinx instead of MkDocs, or swap Vercel for Netlify/Cloudflare Pages as needed.

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.