All jobs

Find and Fix Broken Links in a Docusaurus Site

Yes. An agent builds your Docusaurus site, fixes the broken internal links it reports, adds a weekly external link check with lychee, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Docusaurus checks internal links itself, but only on a production build and only as loudly as the config allows, so the agent starts by reading what the config allows. In a site laid out like electron/website, docusaurus.config.ts sets onBrokenLinks: 'warn', leaves onBrokenAnchors and markdown.hooks.onBrokenMarkdownLinks at their defaults, which also warn, and declares eight locales with a hand-written baseUrl per translated locale. The build script is docusaurus build --locale en, and the only pull request workflow runs yarn lint, never the build, so no link check runs before merge. The .github/problem-matchers/docusaurus.json matcher in push-main.yml turns every [WARNING] line of the publish build into an annotation on main, which is where broken links are seen today, after the fact.

Then it reads where the links come from, because not every broken link in this site can be fixed in this repository. docs/latest/ holds 301 Markdown files mirrored from the electron/electron stable branch by a webhook, with relative links like ../api/menu.md#menuappendmenuitem that scripts/tasks/md-fixers.ts rewrites during pre-build; a broken link there must be fixed upstream or it comes back on the next mirror. The 134 posts under blog/, the pages under src/pages/, sidebars.js, the navbar and footer in the config, and docs/latest/api-history.schema.json are owned here. The agent runs yarn install --immutable and yarn build in its sandbox on Node 24.22.1, keeps the full list of [WARNING] lines, and sorts each one into fix-here or report-upstream by the file it names.

For the links owned here it makes the smallest change that resolves each one: a moved blog slug, a doc id renamed in sidebars.js, an anchor whose heading changed. For links into docs/latest/ it writes the upstream path under docs/ in electron/electron next to each one. Then it decides the config: if the build is clean after the fixes, onBrokenLinks becomes 'throw' and onBrokenAnchors with it, so the next regression fails the build; if mirrored content still has broken links, the setting stays at warn, the pull request says exactly which upstream files hold them, and the description names the commit after which throw can be turned on.

External links are not Docusaurus's job, so the agent adds .github/workflows/links.yml that runs weekly and by hand: it builds the English locale, then runs lychee over build/**/*.html with --base set to the site URL so root-relative links resolve, an accept list that treats 429 as fine, GITHUB_TOKEN so links into github.com are not rate-limited, a cache so a flaky host is retried before it is reported, and a .lycheeignore for the edit-this-page links into electron/electron, localhost, and the Crowdin and Azure hosts that answer differently to a bot. It runs that command once in the sandbox against the built site, reads the external failures, and puts the real ones in the pull request with the pages that link to them.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Find and fix broken links in this Docusaurus site. Read docusaurus.config.ts, sidebars.js, package.json, .nvmrc, scripts/pre-build.ts, scripts/tasks/md-fixers.ts, .github/problem-matchers/docusaurus.json and every workflow under .github/workflows first. Run yarn install --immutable and yarn build in your sandbox and keep every [WARNING] line about links and anchors. Fix the ones in files this repository owns (blog, src, sidebars.js, the config) with the smallest change that resolves each; for the ones in docs/latest, which is mirrored from electron/electron, list the upstream file for each instead of editing. If the build is then clean, set onBrokenLinks and onBrokenAnchors to throw; if not, leave them at warn and say why. Add .github/workflows/links.yml that runs weekly and on workflow_dispatch, builds the en locale and runs lychee over the built HTML with --base set to the site url, a 429 accept, GITHUB_TOKEN, a cache, and a .lycheeignore for edit links, localhost and hosts that refuse bots. Run that lychee command once in the sandbox and put the real external failures with their source pages in the pull request. Do not change docs/latest or the publish workflow.",
  "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 changes the blog posts, pages and sidebars.js entries that held broken links, adds .github/workflows/links.yml and .lycheeignore, and either flips onBrokenLinks and onBrokenAnchors to throw in docusaurus.config.ts or leaves a comment there explaining what still blocks it. Its description has three lists: links fixed here with the before and after, links in mirrored docs with the upstream path for each, and external links lychee reported as dead with the page that carries them.

The test job of pull-request.yml still runs lint only, so the pull request also shows the output of the sandbox build, and the new weekly workflow appears under Actions with a manual trigger for the first run.

Before merging, a reviewer checks the fixed links point where the author meant, decides whether to open the upstream pull request for the mirrored docs now, and prunes the ignore list to the hosts they agree should never be checked.

Run it on every week

Once links.yml is merged, the weekly job finds dead external links, and the question becomes who turns a red run into a fix. An automation on the Project with a github trigger on workflow_run.failure and the prompt "if the failed workflow is links, read its log, and for each dead external link find the page that carries it and either the replacement URL or the archive copy, then open a pull request with the changes" starts one run per failed check. The trigger adds the event after the prompt, and only work by an owner, member or collaborator fires it.

A team with several Docusaurus sites sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own config: a site already on throw skips the config change, and one whose docs are all owned locally fixes everything in one pull request.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A link check is only useful when someone reads the output and knows which failures they can fix. This site's build prints warnings for mirrored content and local content alike, and an external checker reports rate limits beside real dead pages. The agent runs both in its own sandbox, reads every line, and sorts them by who owns the file and whether the host answered honestly.

The build and the lychee output stay with the run, so the pull request shows the warnings before and after the fixes rather than a config change on faith. The same request runs on every site a team maintains at once, and the weekly job it leaves behind keeps the list short.

Frequently asked questions

Why not just set `onBrokenLinks` to `throw`?

Because that fails the publish build on main the next time the mirrored docs carry a broken link, with nothing in this repository to fix. The agent sets it to throw only when the sandbox build is clean after its fixes; otherwise it leaves warn, lists the upstream files, and names the point at which throw becomes safe.

Does Docusaurus check external links?

No. Its onBrokenLinks check covers links between pages of the site and runs only during docusaurus build. External links need a separate tool, which is why the pull request adds a weekly lychee job over the built HTML rather than over the Markdown, so links written by transformers and the navbar are included.

Why run lychee weekly instead of on every pull request?

External checks take minutes of network traffic and fail on other people's outages. On a schedule, a dead link is found within a week and never blocks a contributor; the cache means a host that answered last week is not asked again at once. The job also has workflow_dispatch for a run before a release.

Will the fixes in blog posts change their URLs?

No. The agent changes link targets inside the posts and the ids in sidebars.js, not slugs or file names, so no existing page moves. A fix that would need a redirect is listed in the description as a decision rather than made.

More Docusaurus jobs

The same job on other stacks

Keep reading