Skip to content

Commit dc62747

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 dc62747

File tree

9 files changed

+486
-5
lines changed

9 files changed

+486
-5
lines changed

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Link Checker
2+
run-name: Link Checker (${{ github.event_name }} • ${{ github.ref_name }})
3+
4+
on:
5+
pull_request:
6+
paths:
7+
- 'main/**/*.md'
8+
- 'main/**/*.mdx'
9+
- 'main/**/*.jsx'
10+
- 'auth4genai/**/*.md'
11+
- 'auth4genai/**/*.mdx'
12+
- 'auth4genai/**/*.jsx'
13+
workflow_dispatch: {}
14+
15+
concurrency:
16+
group: ${{ github.workflow }}-${{ github.ref }}
17+
cancel-in-progress: true
18+
19+
jobs:
20+
link-check:
21+
name: Link Checker (${{ matrix.site.name }})
22+
runs-on: ubuntu-latest
23+
permissions:
24+
contents: read
25+
26+
strategy:
27+
fail-fast: false
28+
matrix:
29+
site:
30+
- name: auth0
31+
path: main
32+
- name: auth0-genai
33+
path: auth4genai
34+
35+
steps:
36+
- name: Checkout repo
37+
uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
38+
39+
- name: Get changed files
40+
if: github.event_name == 'pull_request'
41+
id: changed
42+
uses: yumemi-inc/changed-files@50f2544ad88b4f274eace9689431b7281132304c # v3.2.0
43+
with:
44+
patterns: |
45+
${{ matrix.site.path }}/**/*.md
46+
${{ matrix.site.path }}/**/*.mdx
47+
${{ matrix.site.path }}/**/*.jsx
48+
statuses: 'added|modified|renamed'
49+
format: 'plain'
50+
51+
- name: Decide Lychee targets
52+
id: targets
53+
# Only run if:
54+
# - not a PR (manual full scan), OR
55+
# - PR and we actually have changed files
56+
if: >
57+
github.event_name != 'pull_request' ||
58+
steps.changed.outputs.files != ''
59+
run: |
60+
echo "targets=${{ github.event_name == 'pull_request' && steps.changed.outputs.files || format('''{0}/**/*.md'' ''{0}/**/*.mdx'' ''{0}/**/*.jsx''', matrix.site.path) }}" >> "$GITHUB_OUTPUT"
61+
62+
- name: Run Lychee on target
63+
id: lychee
64+
if: steps.targets.outputs.targets != ''
65+
uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0
66+
continue-on-error: true
67+
env:
68+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
69+
with:
70+
fail: false
71+
args: >
72+
--root-dir "$(pwd)/${{ matrix.site.path }}"
73+
--format detailed
74+
--verbose
75+
${{ 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)