# Check for Broken Links in Sphinx Docs with the linkcheck Builder

Yes. An agent adds Sphinx's linkcheck builder to your docs as a tox environment and a weekly workflow, with ignores for what cannot be checked, and opens a PR.

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

## What the agent does

Sphinx ships a link checker, so the agent's first job is to read how the docs are built and which links the checker would hit. In a project laid out like pallets/click, `docs/` holds Markdown pages read by `myst_parser`, and `docs/conf.py` turns on `sphinx.ext.autodoc`, `sphinx.ext.extlinks` with an `issue` and a `pr` role that expand to `https://github.com/pallets/click/issues/%s` and `/pull/%s`, `sphinx.ext.intersphinx` against `https://docs.python.org/3/`, `sphinx_tabs.tabs`, `sphinxcontrib.log_cabinet` and the `click` theme from `pallets_sphinx_themes`, with `myst_heading_anchors = 3`. `pyproject.toml` keeps the docs tools in a `docs` dependency group, and `[tool.tox.env.docs]` builds with `sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml`, so any warning fails the build. `.readthedocs.yaml` runs the same `-W` dirhtml build through `uv run --group docs` on Ubuntu 24.04 with Python 3.13. `uv.lock` resolves Sphinx 9.1.0 on Python 3.12 and later, 9.0.4 on 3.11 and 8.1.3 on 3.10.

Then the agent counts what a `linkcheck` build would request. Across `docs/*.md` there are 79 external URLs: 29 to `github.com`, 16 to `img.shields.io` (the stars and last-commit badges in the project table of `docs/contrib.md`), 6 to `palletsprojects.com`, 5 to `docs.python.org`, and single links to places like `diataxis.fr`, `man7.org` and `http://docopt.org/`. `docs/changes.md` is one line that includes `../CHANGES.md`, and that file carries 599 `{issue}` and `{pr}` references, each of which the checker resolves to a GitHub URL and fetches. GitHub rate-limits that many requests; Sphinx honours `Retry-After` and waits up to `linkcheck_rate_limit_timeout`, 300 seconds by default, so an unconfigured run is slow before it is useful. `docs/commands.md` also has `http://127.0.0.1:{port}/`, a placeholder that is not a URL.

The agent adds the configuration to `docs/conf.py`: a `linkcheck_ignore` list for the issue and pull-request URLs the `extlinks` roles build, for the `img.shields.io` badges, which are images that change on every request, and for the `127.0.0.1:{port}` placeholder; `linkcheck_anchors_ignore_for_url` for `github.com`, whose README anchors are rendered by a script and never appear in the fetched HTML; and `linkcheck_retries = 2` so one dropped connection does not report a working link as broken. It adds `[tool.tox.env.linkcheck]` to `pyproject.toml` with `dependency_groups = ["docs"]` and `sphinx-build -b linkcheck docs docs/_build/linkcheck`, which needs no new package because the builder is part of Sphinx. Then it writes `.github/workflows/links.yaml`: a weekly `schedule` plus `workflow_dispatch`, `permissions: {}`, the same SHA-pinned `actions/checkout`, `astral-sh/setup-uv` and `actions/setup-python` steps as `tests.yaml` with `persist-credentials: false`, a run of `uv run --locked --no-default-groups --group dev tox run -e linkcheck`, and an upload of `docs/_build/linkcheck/output.json` with the pinned `actions/upload-artifact` from `publish.yaml`. `zizmor.yaml` scans every workflow on push, so the file follows the pins and permissions it enforces.

Before opening anything, the agent runs the checker in its sandbox with `uv run --group docs sphinx-build -b linkcheck docs docs/_build/linkcheck`, reads `output.txt` line by line, and sorts what remains into links that are broken, links that redirect to a new canonical page, and links that answer 403 to a non-browser client. A permanent redirect gets the new URL in the Markdown; a page that is gone gets removed or replaced; a host that refuses automated clients goes into `linkcheck_ignore` with a comment saying why. It then runs `tox run -e docs` to confirm the `-W` build still passes, `pre-commit run --all-files` so `ruff-format` and `codespell` accept the edited `conf.py`, and `uvx zizmor .github/workflows/links.yaml` on the new workflow.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add external link checking to this Sphinx documentation. Read docs/conf.py, pyproject.toml, .readthedocs.yaml, .pre-commit-config.yaml and every workflow under .github/workflows first, and count the external links in docs/ including anything docs/changes.md includes. Configure the linkcheck builder in docs/conf.py: ignore the GitHub issue and pull request URLs that the extlinks roles generate, the img.shields.io badges and any placeholder URL with braces in it; skip anchor checks for github.com; set a small retry count. Add a tox environment named linkcheck in pyproject.toml that uses the docs dependency group and runs sphinx-build -b linkcheck docs docs/_build/linkcheck. Add .github/workflows/links.yaml on a weekly schedule and workflow_dispatch, with permissions: {}, the same SHA-pinned checkout, setup-uv and setup-python steps as tests.yaml, persist-credentials false, and an artifact upload of docs/_build/linkcheck/output.json. Run the linkcheck build here, fix links that redirect permanently or are gone, add any host that blocks automated requests to the ignore list with a comment, then run tox run -e docs, pre-commit run --all-files and uvx zizmor on the new workflow. Open a pull request with the output.txt summary in its description.",
  "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 `docs/conf.py`, `pyproject.toml` and whichever Markdown pages had a link worth fixing, and adds `.github/workflows/links.yaml`. Its description pastes the end of `output.txt`, grouped into what was fixed, what was ignored and why, and what is still broken for the maintainers to decide on, with the `tox run -e docs` and `pre-commit` results beneath.

On the pull request, the `pre-commit` workflow checks the formatting of `conf.py` and `zizmor` scans the new workflow file. The `Tests` workflow skips `docs/**` changes by its `paths-ignore`, so the docs build itself is proven by the run's record and by Read the Docs, which builds every pull request with the same `-W` flag.

Before merging, a reviewer reads the ignore list: every pattern there is a link nobody will check again, so each needs a reason in a comment. They also decide whether the weekly schedule is enough or whether the job should also run on pull requests that touch `docs/`, and whether the `linkcheck` environment belongs in `env_list` so `tox run` with no arguments includes it.

## Run it on every Sphinx repository you maintain

A team with several Sphinx projects starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with this prompt as `input`, 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. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so the script can pick the ones with a `docs/conf.py` and no `linkcheck` environment. Each run reads its own `conf.py`, so a project whose changelog uses different roles, or that builds with `make html` instead of tox, gets ignores and a workflow shaped to it.

A team that files documentation work in Linear runs the same prompt from an automation in the Project with a `linear` trigger on issues labelled `docs`. The trigger adds the issue after the prompt, so an issue that names a host to skip or asks for the check on every pull request reaches the agent with that detail, and the pull request links back to it.

## Why run it on Rush?

A linkcheck build is minutes of network traffic against hundreds of hosts, and its value is in reading the output, not in running it. On a laptop the run competes with everything else on the connection and the output scrolls away. In its own sandbox the agent runs it to completion, keeps `output.txt` and `output.json` with the run, and the decision behind every ignore pattern is written next to the request that produced it.

The same prompt runs across every documentation repository at once, each in its own sandbox with its own pull request, and the sandbox runs the project's own tooling, so `tox`, `pre-commit` and `zizmor` pass before a maintainer sees the change rather than after.

## Frequently asked questions

### Will a broken link fail the Read the Docs build?

No. `linkcheck` is a separate builder with its own output directory, and `.readthedocs.yaml` keeps running `sphinx-build -W -b dirhtml`. A dead external link is reported by the weekly job, not by the docs build, which is why the workflow is scheduled rather than attached to the `docs` tox environment.

### Why ignore the GitHub issue and pull request links?

The `issue` and `pr` roles in `conf.py` build every reference in `CHANGES.md` into a GitHub URL, and that file has 599 of them. Checking each one means hundreds of requests to one host that rate-limits, for links a maintainer typed as a number and that GitHub never removes. Ignoring the pattern keeps the run short and the report about the links that can actually rot.

### Does it check the badges in contrib.md?

Sphinx's linkcheck fetches image URLs too, and the stars and last-commit badges from `img.shields.io` are regenerated on every request. The agent adds that host to `linkcheck_ignore`; a broken project link in the same table row is still checked through its `github.com` URL.

### Can it run on every pull request instead of weekly?

It can, with a `pull_request` trigger limited to `docs/**` and `CHANGES.md`, but external links fail for reasons unrelated to the change, so a required check would block unrelated work. The agent sets a schedule and `workflow_dispatch` by default and says in the pull request how to add the pull-request trigger if the team wants it.

### What about the intersphinx references to the Python docs?

Those resolve against the inventory `sphinx.ext.intersphinx` downloads once at build time, not through a request per reference, so they are not part of the linkcheck report. Only explicit URLs in the Markdown, including the ones `extlinks` roles expand to, are fetched.

## More Sphinx jobs

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

## The same job on other stacks

- [Check for Broken Links in a Starlight Docs Site](https://getrush.ai/run/add-link-checking/starlight/)
- [Add Link Checking to a VitePress Site](https://getrush.ai/run/add-link-checking/vitepress/)
- [Add Link Checking to a Zola Site](https://getrush.ai/run/add-link-checking/zola/)

## 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/)
