docs/.github/workflows/_check-links.yml at main · AgentLineHQ/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# Documentation Build & Link Validation
#
# This reusable workflow builds documentation using Python/Make and validates
# all internal and external links using Mintlify's link checker.
#
# Usage:
#   jobs:
#     docs-validation:
#       uses: ./.github/workflows/_check-links.yml
#       with:
#         python-version: "3.13"
#
# Requirements:
#   - A Makefile with a 'build' target in the repository root
#   - Python dependencies managed via uv with a 'test' group
#   - Generated documentation compatible with Mintlify link checker

name: Documentation Build & Link Validation

on:
  workflow_call:
    inputs:
      python-version:
        required: true
        type: string
        description: "Python version for building documentation (e.g., '3.13')"

env:
  UV_FROZEN: "true"
  UV_NO_SYNC: "true"

jobs:
  check-links:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 20
    name: "Documentation Build & Link Check (Python ${{ inputs.python-version }})"
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - name: Configure Python ${{ inputs.python-version }} with uv package manager
        uses: "./.github/actions/uv_setup"
        id: setup-python
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install Python dependencies
        shell: bash
        run: uv sync --group test

      - name: Configure Node.js runtime
        uses: actions/setup-node@v6
        with:
          node-version: '22'

      - name: Resolve npm global prefix
        id: npm-paths
        run: |
          PREFIX="$(npm prefix -g)"
          echo "root=${PREFIX}/lib/node_modules" >> "$GITHUB_OUTPUT"
          echo "bin=${PREFIX}/bin" >> "$GITHUB_OUTPUT"

      - name: Cache Mintlify CLI
        id: cache-mint
        uses: actions/cache@v5
        with:
          path: |
            ${{ steps.npm-paths.outputs.root }}/mint
            ${{ steps.npm-paths.outputs.bin }}/mint
          key: mintlify-${{ runner.os }}-node-22-${{ hashFiles('.github/workflows/_check-links.yml') }}
          restore-keys: |
            mintlify-${{ runner.os }}-node-22-

      - name: Install Mintlify CLI
        if: steps.cache-mint.outputs.cache-hit != 'true'
        run: npm i -g mint@latest

      - name: Patch KaTeX __VERSION__ bug
        if: steps.cache-mint.outputs.cache-hit != 'true'
        run: |
          KATEX_DIR="$(npm root -g)/mint/node_modules/katex"
          KATEX_MJS="$KATEX_DIR/dist/katex.mjs"
          if [ -f "$KATEX_MJS" ]; then
            VERSION=$(node -e "console.log(require('$KATEX_DIR/package.json').version)")
            sed -i "s/__VERSION__/\"$VERSION\"/g" "$KATEX_MJS"
          fi

      - name: Validate documentation links
        run: make broken-links-with-anchors

      - name: Validate openapi spec validity
        run: make check-openapi