Add link checker GitHub workflow

[btiernay]

📝 Before you begin

By opening this PR, you agree to the terms of the Auth0 Code of Conduct. For guidance on creating a high-quality PR, see the Contributing Guidelines.

✏️ Changes

This PR wires up automated external-link checking for both the main and auth4genai Mintlify docs using Lychee. It adds a GitHub Actions workflow, centralizes link-check configuration in lychee.toml, and updates the READMEs so people know how to run the checks locally.

• Problem solved: Catch broken external links (404s, bad certs, consistent 503s, etc.) in docs before they reach production
• Docs/UI areas affected: Both main/ and auth4genai/ documentation sites
• Scope: Adds a CI workflow, shared Lychee config, and documentation updates

📁 Documentation scope

Docs site(s) affected

• main/
• auth4genai/

Other areas

• Shared UI library (ui/)
• GitHub workflows (.github/workflows/)
• Tooling or scripts (tools/)

Type of change

• New page or major section
• Update to existing content
• Navigation or structure change
• Code examples or snippets
• UI component or Mintlify configuration
• GitHub workflows (.github/workflows/)
• Scripts or tooling (tools/)

Paths:

• .github/workflows/link-check.yml
• lychee.toml
• auth4genai/README.md
• main/README.md

🔗 References

• Lychee link checker
• Lychee config reference

🎯 Testing

Local validation

• Content-only change (no build or navigation impact)
• mint dev in affected folders
• mint broken-links (when applicable)
• mint a11y (when applicable)
• npm run build in ui/ (for UI changes)

Style and structure

• Follows the Contributing Guidelines
• Uses correct Auth0 terminology
• Code blocks include language and filenames when needed

Repo checks

• All required GitHub checks are passing
• The correct base branch is used

Notes: Workflow exercised via manual dispatch and PRs. Currently configured as warning-only (continue-on-error: true, fail: false) while excludes settle.

🔄 Redirects

Not applicable – no URL changes.

🌍 Internationalization (main docs only)

• Not applicable – no English content changes in main/

🧩 Impact and dependencies

User-facing impact

• New automated checks for external links in both documentation trees
• Two separate checks appear in PR status:
  • Link Checker (auth0)
  • Link Checker (auth0-genai)
• Checks are non-blocking for now; they surface broken links but do not prevent merges

Dependencies

None.

🚀 Deployment

• Safe to deploy on merge

📝 Follow-up

• No follow-up needed
• Follow-up work required

Next steps:

• Tighten exclude patterns in lychee.toml as more noisy URLs show up
• Decide when to make the checks required / blocking
• Consider enabling fragment checking (include_fragments = true) once the baseline is stable

💬 Additional context

What’s included

GitHub Actions workflow

A new workflow at .github/workflows/link-check.yml that:

• runs on pull requests that touch docs in main/ or auth4genai/
• can be run manually via workflow_dispatch (full scan for both sites)
• uses a simple matrix to run separately for:
  • auth0 → main/
  • auth0-genai → auth4genai/
• on PRs:
  • uses yumemi-inc/changed-files to detect changed .md, .mdx, .jsx files per site
  • only runs Lychee on files that actually changed
• on manual runs:
  • scans **/*.md, **/*.mdx, **/*.jsx for each site
• runs Lychee via lycheeverse/lychee-action with --root-dir set to the site root, so root-relative paths resolve correctly against the filesystem
• pins all actions to specific commit hashes

Each site shows up as its own check in the PR UI:

• Link Checker (auth0)
• Link Checker (auth0-genai)

Lychee configuration

lychee.toml now holds all shared config:

• enables caching (cache = true) and disables progress output for CI
• defines accept codes for common “not really broken” responses (302, 307, 403, 429)
• sets fallback extensions for Mintlify (md, mdx)
• turns off fragment checking for now (include_fragments = false)
• centralizes a curated exclude list that filters out:
  • URLs that require authentication (Auth0 Dashboard, Oktawiki, etc.)
  • sites that consistently block or throttle bots (npmjs.com, LinkedIn, Cloudflare, Constant Contact KB, some W3C / OpenID PDFs)
  • API-only endpoints and placeholders
  • root-relative file:// URLs that cannot be resolved reliably in this repo

This replaces ad hoc ignores and keeps CI + local runs using the same rules.

Documentation updates

main/README.md and auth4genai/README.md now include:

• a short section on how to run Lychee locally with:
  • --base-url when you care about how links behave on auth0.com / auth0.com/ai/docs
  • --root-dir when you want to validate links against the local repo layout

Usage

Automated

Lychee runs automatically:

• on pull requests that touch main/**/*.md[x|jsx] or auth4genai/**/*.md[x|jsx]
• per site, via the auth0 / auth0-genai matrix

Each run respects lychee.toml.

Manual

From the Actions tab:

1. Open Link Checker
2. Click Run workflow (no inputs)
3. Wait for:
   • Link Checker (auth0)
   • Link Checker (auth0-genai)

Both sites are scanned in full.

Local examples

Against live auth0.com docs (external behavior):

lychee --format detailed --verbose \
  --base-url https://auth0.com \
  'main/**/*.md' 'main/**/*.mdx' 'main/**/*.jsx'

Against the local main/ tree (filesystem behavior):

lychee --format detailed --verbose \
  --root-dir "$(pwd)/main" \
  'main/**/*.md' 'main/**/*.mdx' 'main/**/*.jsx'

Swap main for auth4genai and https://auth0.com/ai/docs if you want to target the AI docs.

Lychee will pick up lychee.toml automatically in all these cases.

[btiernay]

Note: this workflow is currently running in “soft” mode. It reports broken links but never fails the build. That gives us time to watch how noisy/flake-y it is before turning it into a blocking check.

[btiernay]

These specifically need addressing in another round