claude-howto/.github/workflows/docs-check.yml

name: Documentation Checks

on:
  push:
    branches: [main]
    paths:
      - '**.md'
      - '.github/workflows/docs-check.yml'
      - '.github/markdown-link-check-config.json'
      - '.markdownlint.json'
      - 'scripts/check_*.py'
  pull_request:
    branches: [main]
    paths:
      - '**.md'
      - 'CONTRIBUTING.md'
      - 'LICENSE'
      - '.github/markdown-link-check-config.json'
      - '.markdownlint.json'
      - 'scripts/check_*.py'

# Cancel in-progress runs for the same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  markdown-lint:
    name: Markdown Linting
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install markdownlint-cli
        run: npm install -g markdownlint-cli

      - name: Run Markdown Linter
        run: markdownlint '**/*.md' --ignore node_modules --ignore .venv --config .markdownlint.json

  link-check:
    name: Check Links
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Run link check
        run: python scripts/check_links.py
        env:
          LINK_CHECK_STRICT: "1"

  mermaid:
    name: Mermaid Syntax
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Validate Mermaid diagrams
        run: python scripts/check_mermaid.py
        env:
          MERMAID_PUPPETEER_NO_SANDBOX: "true"

  cross-references:
    name: Cross-reference Check
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Validate cross-references
        run: python scripts/check_cross_references.py

  summary:
    name: Summary
    needs: [markdown-lint, link-check, mermaid, cross-references]
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Check Job Results
        run: |
          if [ "${{ needs.markdown-lint.result }}" = "failure" ] || \
             [ "${{ needs.link-check.result }}" = "failure" ] || \
             [ "${{ needs.mermaid.result }}" = "failure" ] || \
             [ "${{ needs.cross-references.result }}" = "failure" ]; then
            echo "❌ Some documentation checks failed"
            exit 1
          else
            echo "✅ All documentation checks passed!"
          fi