Skip to content

Commit 8510fbd

Browse files
btiernaybtiernay
committed
chore: add link checker workflow for documentation
Add lychee-based link checking workflow with comprehensive configuration: - GitHub Actions workflow for automated link validation - Custom lychee.toml configuration with exclusions and retry logic - Documentation updates and minor fixes
1 parent d265a87 commit 8510fbd

File tree

9 files changed

+514
-5
lines changed

9 files changed

+514
-5
lines changed

‎.github/workflows/link-check.yml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
name: Link Checker
2+
run-name: Link Checker (${{ github.event_name }} • ${{ github.ref_name }})
3+
4+
on:
5+
pull_request:
6+
paths:
7+
# Only run when docs files change in either site
8+
- 'main/**/*.md'
9+
- 'main/**/*.mdx'
10+
- 'main/**/*.jsx'
11+
- 'auth4genai/**/*.md'
12+
- 'auth4genai/**/*.mdx'
13+
- 'auth4genai/**/*.jsx'
14+
workflow_dispatch: {} # Manual run (full scan for both sites)
15+
16+
concurrency:
17+
# One link-check run per ref; newer runs cancel older ones on the same branch/PR
18+
group: ${{ github.workflow }}-${{ github.ref }}
19+
cancel-in-progress: true
20+
21+
jobs:
22+
link-check:
23+
name: Link Checker (${{ matrix.site.name }})
24+
runs-on: ubuntu-latest
25+
permissions:
26+
contents: read # required by checkout and changed-files
27+
28+
strategy:
29+
# If one site fails (auth0 vs auth0-genai), do not cancel the other
30+
fail-fast: false
31+
matrix:
32+
site:
33+
- name: auth0
34+
path: main
35+
- name: auth0-genai
36+
path: auth4genai
37+
38+
steps:
39+
- name: Checkout repo
40+
# https://github.com/actions/checkout
41+
# Pin to v6.0.0 tag commit for supply-chain safety
42+
uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
43+
44+
- name: Get changed files
45+
# Only needed on PRs; for manual runs we always scan everything
46+
if: github.event_name == 'pull_request'
47+
id: changed
48+
# https://github.com/yumemi-inc/changed-files
49+
# Pin to v3.2.0 tag commit for supply-chain safety
50+
uses: yumemi-inc/changed-files@50f2544ad88b4f274eace9689431b7281132304c # v3.2.0
51+
with:
52+
# Only consider docs files in the current site (from the matrix)
53+
patterns: |
54+
${{ matrix.site.path }}/**/*.md
55+
${{ matrix.site.path }}/**/*.mdx
56+
${{ matrix.site.path }}/**/*.jsx
57+
# Ignore deletions; we care about content that still exists
58+
statuses: 'added|modified|renamed'
59+
# Plain space-separated list, easier to feed into lychee args
60+
format: 'plain'
61+
62+
- name: Decide Lychee targets
63+
id: targets
64+
# Run if:
65+
# - not a PR (manual full scan), OR
66+
# - PR with at least one changed file in this site
67+
if: >
68+
github.event_name != 'pull_request' ||
69+
steps.changed.outputs.files != ''
70+
run: |
71+
# On PRs, use the list of changed files from the previous step.
72+
# On manual runs, scan the whole docs tree for that site.
73+
echo "targets=${{ github.event_name == 'pull_request' && steps.changed.outputs.files || format('''{0}/**/*.md'' ''{0}/**/*.mdx'' ''{0}/**/*.jsx''', matrix.site.path) }}" >> "$GITHUB_OUTPUT"
74+
75+
- name: Run Lychee on target
76+
id: lychee
77+
# Skip if we somehow ended up with no targets
78+
if: steps.targets.outputs.targets != ''
79+
# https://github.com/lycheeverse/lychee-action
80+
# Pin to v2.7.0 tag commit
81+
uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0
82+
continue-on-error: true # let the job finish and report even if links are broken
83+
env:
84+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # used for GitHub API calls (e.g. rate limits, private links)
85+
with:
86+
fail: false # FIXME: Once the config, links, and fixes have stabilized, we should enable for hard block. For now this is just informative
87+
# Important bits:
88+
# - --root-dir ties file:// URLs to the correct site root
89+
# - --format detailed + --verbose for useful CI logs
90+
# - ${targets} is either changed files (PR) or whole tree (manual run)
91+
args: >
92+
--root-dir "$(pwd)/${{ matrix.site.path }}"
93+
--format detailed
94+
--verbose
95+
${{ steps.targets.outputs.targets }}

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ temp/
66
*.py
77

88
.vite
9+
10+
.lycheecache

‎README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,3 +63,56 @@ pnpm add -g mint
6363
- **Custom port**: `mint dev --port 3333`
6464

6565
For more details, see the [Mintlify CLI documentation](https://mintlify.com/docs/installation).
66+
67+
## Link Checking
68+
69+
We use [Lychee](https://lychee.cli.rs/) to check for broken links across both documentation sites (`main/` and `auth4genai/`).
70+
All configuration and exclusions live in [`lychee.toml`](lychee.toml), and both local runs and CI use the same rules.
71+
72+
### Local Usage
73+
74+
There are two recommended ways to check links locally, depending on what you want to validate.
75+
76+
#### 1. Check links as they behave on auth0.com
77+
78+
This mode asks Lychee to treat absolute paths like `/docs/...` as if they were being loaded from the live site.
79+
It is useful when you want to confirm that public links resolve correctly through redirects, locale routing, or dynamically rendered pages.
80+
81+
**Main docs:**
82+
```bash
83+
lychee --format detailed --verbose --base-url https://auth0.com \
84+
'main/**/*.md' 'main/**/*.mdx' 'main/**/*.jsx'
85+
````
86+
87+
**Auth0 for AI Agents docs:**
88+
89+
```bash
90+
lychee --format detailed --verbose --base-url https://auth0.com/ai/docs \
91+
'auth4genai/**/*.md' 'auth4genai/**/*.mdx' 'auth4genai/**/*.jsx'
92+
```
93+
94+
#### 2. Check links against the local filesystem
95+
96+
This mode validates only links that actually exist in the repo.
97+
It is useful when you’re working on local references (images, snippets, relative paths) and want to ensure nothing in the tree is broken.
98+
99+
**Main docs:**
100+
101+
```bash
102+
lychee --format detailed --verbose --root-dir "$(pwd)/main" \
103+
'main/**/*.md' 'main/**/*.mdx' 'main/**/*.jsx'
104+
```
105+
106+
**Auth0 for AI Agents docs:**
107+
108+
```bash
109+
lychee --format detailed --verbose --root-dir "$(pwd)/auth4genai" \
110+
'auth4genai/**/*.md' 'auth4genai/**/*.mdx' 'auth4genai/**/*.jsx'
111+
```
112+
113+
### Notes
114+
115+
* You can combine `--base-url` and glob patterns however you like; the examples above are the patterns used in CI.
116+
* Any URLs that need to be ignored should be added to `lychee.toml`, not passed on the command line.
117+
* Lychee caches results locally, so repeat runs are much faster.
118+
* Mintlify already checks internal routes during `mint dev`, so Lychee is mainly for external links and static references.

‎auth4genai/.vale/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Vale parses `.mdx` files using `mdx2vast`. The parser automatically ignores:
5454
* JSX components and JSX blocks
5555
* fenced code blocks
5656
* inline backtick code
57-
* URLs (see [URL handling](https://vale.sh/docs/topics/urls))
57+
* URLs (see Vale’s URL handling notes: https://github.com/errata-ai/vale/issues/320)
5858
* single-line `{ ... }` JavaScript expressions
5959
6060
These defaults help avoid false positives in pages that combine prose with examples, components, and structured metadata.

‎auth4genai/how-tos/analyze-strava-activities.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Learn how to use Auth0 for AI Agents SDKs to analyze Strava activit
44
mode: "wide"
55
---
66

7-
Use the [Vercel AI SDK](https://sdk.vercel./introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to analyze user fitness activity from Strava.
7+
Use the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to analyze user fitness activity from Strava.
88

99
<Card title="Prerequisites">
1010
Before using this example, make sure you:

‎auth4genai/how-tos/create-spotify-playlist.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Learn how to use Auth0 for AI Agents SDKs to create a Spotify playl
44
mode: "wide"
55
---
66

7-
Use the [Vercel AI SDK](https://sdk.vercel./introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to create personalized Spotify playlists based on user input like mood, vibe, or activity.
7+
Use the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to create personalized Spotify playlists based on user input like mood, vibe, or activity.
88

99
<Card title="Prerequisites">
1010
Before using this example, make sure you:

‎auth4genai/snippets/get-started/vercel-ai-next-js/user-authentication.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ Sign up for your application to create a new user account. You will then see a w
6767
>
6868
### Install Auth0 Next.js SDK
6969

70-
In the root directory of your project, install the [Auth0 Next.js SDK](http://next.js/):
70+
In the root directory of your project, install the [Auth0 Next.js SDK](https://github.com/auth0/nextjs-auth0):
7171

7272
```bash wrap lines
7373
npm i @auth0/nextjs-auth0@4

0 commit comments

Comments
 (0)