# Add Link Checking to a VitePress Site

Yes. An agent adds a lychee workflow that checks every external link in your VitePress posts on pull requests and weekly, with an ignore list that fits your site.

[Run this on Rush](https://cloud.getrush.ai/run/add-link-checking/vitepress/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with what VitePress already checks and what it does not. In a site laid out like vuejs/blog, `.vitepress/config.ts` sets `cleanUrls: true` and a `buildEnd` hook, `genFeed`, that loads `posts/*.md` with `createContentLoader` and writes `feed.rss` into the output directory; `package.json` pins `vitepress` 1.3.4 under `packageManager: pnpm@9.8.0` with `build` as `vitepress build`. VitePress fails that build on a dead internal link unless `ignoreDeadLinks` is set, and the config does not set it, so links between posts are covered. External links are not: the 15 posts under `posts/` carry 262 `https://` links, most to github.com, vuejs.org, v3.vuejs.org, vitepress.dev and vitejs.dev, and some to repositories that have since moved or to archived documentation sites. There is no `.github/` directory; the site deploys through `vercel.json`, which sets `cleanUrls` and a cache header for `/assets/`.

The agent adds `.github/workflows/links.yml` with two triggers: `pull_request` filtered to `posts/**`, `index.md` and the workflow file, and a weekly `schedule`. Its one step runs `lycheeverse/lychee-action` over `posts/**/*.md` and `index.md`. On a pull request it checks only the changed files, so a new post is checked without re-fetching every old link; on the schedule it checks everything with `fail: false` and a second step, `peter-evans/create-issue-from-file`, opens an issue from lychee's report, the pattern the action's own README shows, because a link that dies in a five-year-old post is a maintenance task, not a pull request failure.

A link checker on a real site needs an ignore list or it cries wolf, so the agent writes `.lycheeignore` from what it sees in the posts: twitter.com answers checkers with 403, chrome.google.com extension pages and marketplace.visualstudio.com return errors to non-browser clients, and jsdelivr CDN links to pinned versions are fine but slow. It passes `--accept 200..=204,429` so a rate-limited answer is not a failure, and `--max-concurrency` low enough that github.com does not throttle the run. Redirected links, such as the `vuejs/vue-next` repository links that now land on `vuejs/core`, pass; lychee follows redirects and the agent leaves them for a later cleanup rather than editing posts.

Before opening the pull request the agent runs lychee in its sandbox over all 15 posts, reads the report, and sorts every failure into one of three bins: a real dead link, which it lists in the pull request description with the post and line; a site that blocks checkers, which goes into `.lycheeignore` with a comment naming the status it returned; and a transient error, which it retries. It fixes no post text, so the first scheduled run starts from the list in the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add external link checking to this VitePress site. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, vercel.json and every file under posts/ first; note that VitePress already fails the build on dead internal links, so this is about external ones. Add .github/workflows/links.yml using lycheeverse/lychee-action: on pull requests that touch posts/**, index.md or the workflow, check only the changed Markdown files; on a weekly schedule, check every post with fail: false and open an issue from the report with peter-evans/create-issue-from-file, giving that job issues: write. Write a .lycheeignore for hosts that block checkers (twitter.com, chrome.google.com, marketplace.visualstudio.com) with a comment per line saying why, accept 429 as not-a-failure, and keep concurrency low so github.com does not throttle the run. Run lychee over all posts in your sandbox, sort each failure into dead link, blocked host or transient, and list the dead links with their post and line in the pull request description. Do not edit any post.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `.github/workflows/links.yml` and `.lycheeignore` and changes nothing else. Its description has the lychee summary from the sandbox run and a table of links the agent judged dead, each with the post file and line, so the site's maintainers can fix or remove them in a separate change.

On the pull request the new check runs over the two added files and passes, since neither contains a link. From then on a pull request adding a post with a mistyped URL fails with the status lychee got, and the weekly run files an issue, through the second step with its `issues: write` permission, when something old breaks. VitePress's own build is untouched: `vitepress build` still fails on a dead internal link, and `genFeed` still writes the feed.

Before merging, a reviewer reads `.lycheeignore` line by line, because every entry is a host the site will never check again, and decides whether the weekly report should open an issue or post to a channel they already watch.

## Run it on every new post

The workflow is the recurring part: each pull request that adds a post gets its links checked and the weekly schedule catches rot. The run on Rush is the one-time setup, and a team with several VitePress sites sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository name, so a retry does not open a second pull request.

Each run reads its own site: a documentation site with versioned folders gets a different `paths` filter, one with `ignoreDeadLinks: true` in its config gets internal links added to the check as well, and one that already has a workflow directory gets the new file in that directory's style.

## Why run it on Rush?

Any developer can paste a lychee workflow. What takes the time is the first run: fetching a few hundred links, reading which failures are real, which hosts refuse bots, and which are rate limits, then writing an ignore list that is honest about each entry. The agent does that in its own sandbox with the real responses in front of it, and the pull request carries the sorted result rather than a workflow that fails on its first scheduled run for reasons nobody triaged.

The run keeps the commands and the lychee output, so a reviewer can check why a host was ignored. Several sites can get the same treatment at once, each with an ignore list that reflects its own links.

## Frequently asked questions

### Does VitePress not check links already?

It checks internal links: `vitepress build` fails on a link to a page that does not exist unless `ignoreDeadLinks` is set, and this config does not set it. It never fetches external URLs. lychee covers those.

### Why run the full check on a schedule rather than on every pull request?

A full run fetches every link in every post and depends on a few hundred other servers. On a pull request that is slow and flaky for a change that touched one file. Checking only changed files on pull requests and everything weekly keeps the pull request signal clean and still catches links that die later.

### What goes in .lycheeignore?

Hosts that answer checkers with an error regardless of the link's health, such as twitter.com and the Chrome Web Store, each with a comment saying what status the agent saw. The list is short on purpose; a reviewer should be able to read it in a minute.

### Will it fail on links that redirect?

No. lychee follows redirects, so a link to a repository that was renamed passes as long as the destination answers. The agent notes such links in the pull request description if there are many, but does not treat them as failures.

## More VitePress jobs

- [Add llms.txt to a VitePress Blog](https://getrush.ai/run/add-llms-txt/vitepress/)
- [Add Mermaid Diagrams to a VitePress Site](https://getrush.ai/run/add-mermaid-diagrams/vitepress/)
- [Add Open Graph Tags to a VitePress Blog](https://getrush.ai/run/add-open-graph-tags/vitepress/)

## The same job on other stacks

- [Add Link Checking to a Zola Site](https://getrush.ai/run/add-link-checking/zola/)
- [Check for Broken Links in an Astro Site's CI](https://getrush.ai/run/add-link-checking/astro/)
- [Find and Fix Broken Links in a Docusaurus Site](https://getrush.ai/run/add-link-checking/docusaurus/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
