doc-tests.yaml

name: Lint (Docs)
run-name: Lint (Docs)
on:
  pull_request:
    paths:
      - 'CHANGELOG.md'
      - 'docs/**'
      - 'examples/**'
  merge_group:
    paths:
      - 'docs/**'
      - 'examples/**'
      - 'CHANGELOG.md'

jobs:
  doc-tests:
    name: Lint (Docs)
    if: ${{ !startsWith(github.head_ref, 'dependabot/') }}
    runs-on: ubuntu-latest

    permissions:
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          repository: "gravitational/docs"
          path: "docs"

      - name: Prepare docs site configuration
        # The environment we use for linting the docs differs from the one we
        # use for the live docs site in that we only test a single version of
        # the content.
        #
        # To do this, we replace the three submodules we use for building the
        # live docs site with a single submodule, pointing to the
        # gravitational/teleport branch we are linting.
        #
        # The docs engine expects a config.json file at the root of the
        # gravitational/docs clone that associates directories with git
        # submodules. By default, these directories represent versioned branches
        # of gravitational/teleport. We override this in order to build only a
        # single version of the docs.
        run: |
          if [ $GITHUB_EVENT_NAME = "pull_request" ]; then
            BRANCH=$GITHUB_HEAD_REF;
          elif [ $GITHUB_EVENT_NAME = "merge_group" ]; then
            # GitHub populates $GITHUB_REF with:
            # refs/heads/gh-readonly-queue/<base branch>/pr-<PR number>-<SHA>
            #
            # We strip the "refs/heads/" prefix so we can check out the branch.
            BRANCH=$(echo $GITHUB_REF | sed -E "s|refs/heads/(.*)|\1|")
          else
            echo "Unexpected event name: $GITHUB_EVENT_NAME";
            exit 1;
          fi

          cd $GITHUB_WORKSPACE/docs
          echo "" > .gitmodules
          rm -rf content/*
          cd content
          git submodule add --force -b $BRANCH -- https://github.com/gravitational/teleport
          cd $GITHUB_WORKSPACE/docs
          echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
          yarn install
          yarn build-node

      - name: Check spelling
        run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport

      - name: Lint the docs
        run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint

      - name: Test the docs build
        run: cd $GITHUB_WORKSPACE/docs && yarn install && yarn build