fern-docs-ci.yml

# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

# Validates Fern configuration and checks for broken links on pull requests
# that touch docs/** or fern/** files.

name: Fern Docs (CI)

on:
  push:
    branches:
      - "pull-request/[0-9]+"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  changed-files:
    runs-on: linux-amd64-cpu32
    outputs:
      docs: ${{ steps.changes.outputs.docs }}
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          fetch-depth: 0

      - name: Check for docs changes
        id: changes
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            echo "docs=true" >> $GITHUB_OUTPUT
          elif [ "${{ github.event.before }}" = "0000000000000000000000000000000000000000" ]; then
            echo "docs=true" >> $GITHUB_OUTPUT
          elif git diff --name-only "${{ github.event.before }}" HEAD 2>/dev/null | grep -qE '^(docs/|fern/)'; then
            echo "docs=true" >> $GITHUB_OUTPUT
          else
            echo "docs=false" >> $GITHUB_OUTPUT
          fi

  fern-check:
    name: Fern Configuration Check
    needs: changed-files
    if: needs.changed-files.outputs.docs == 'true'
    runs-on: linux-amd64-cpu32
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: Setup Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
        with:
          node-version: '20'

      - name: Install Fern CLI
        run: npm install -g fern-api@$(jq -r .version fern/fern.config.json)

      - name: Check MDX safety
        # Intentionally inline — a composite action would add indirection without benefit for a single grep.
        run: |
          BAD=$(grep -rn '<img\b[^>]*[^/]>\|<img>' docs/ fern/ --include="*.md" --include="*.mdx" || true)
          if [ -n "$BAD" ]; then
            echo "::error::Non-self-closing <img> tags found (MDX requires <img ... />):"
            echo "$BAD"
            exit 1
          fi

      - name: Validate Fern configuration
        run: fern check

      - name: Warn on non-lowercase or underscore markdown filenames
        # TODO: convert to a hard failure once existing violations are resolved
        run: |
          find docs/ -name "*.md" | while read f; do
            base=$(basename "$f")
            if echo "$base" | grep -qE '[A-Z]|_'; then
              suggested=$(echo "$base" | tr '[:upper:]' '[:lower:]' | tr '_' '-')
              echo "::warning file=$f::Filename '$base' should be lowercase with hyphens (e.g. '$suggested')"
            fi
          done

      - name: Check for broken links
        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8  # v2.9.0
        with:
          args: --offline --no-progress 'docs/**/*.md'
          fail: true