# Check for Broken Links in a Hugo Site's CI

Yes. An agent makes Hugo's link render hook fail the build on a bad internal link, adds lychee over the built site and a weekly external check, and opens a PR.

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

## What the agent does

The agent reads how the site is built and what already checks links before adding a tool. In a site like gohugoio/hugoDocs, `hugo.toml` sets `baseURL` to `https://gohugo.io/`, mounts `content/en` as the content root, requires Hugo 0.144.0 or later, writes Netlify's `_redirects` and `_headers` from the `redir` and `headers` output formats, and sets `params.render_hooks.link.errorLevel` to `warning`. That setting drives `layouts/_markup/render-link.html`, a render hook that resolves every internal link destination against a content page, a page resource, a section resource or a global asset and, at `warning`, logs each one it cannot resolve; external destinations pass through untouched. `netlify.toml` builds production with `npm ls && hugo --gc --minify` on `HUGO_VERSION` 0.169.0, `package.json` brings Tailwind 4 and Alpine.js, `go.mod` and `hugo.work` make the site a Go module, and `.github/workflows/lint.yml` runs markdownlint-cli2, cspell, codespell and a `gotmplfmt` check on push and pull request, with every action pinned to a commit SHA and a version comment. `.gitignore` ignores `public/`, `resources/`, `hugo_stats.json` and `package-lock.json`, so installs use `npm i`, and `AGENTS.md` says never to edit the generated `content/en/commands/**` or `data/docs.yaml`.

The first change costs nothing new: the agent installs Hugo extended 0.169.0 in its sandbox, runs `npm i` and `hugo --gc --minify`, and reads the build log. If the link hook reports no unresolved destination on the current content, it raises `errorLevel` to `error` in `hugo.toml`, so the next renamed page fails the Netlify build and any workflow that builds the site instead of logging a warning nobody reads. If the log does show unresolved links, it fixes them in the Markdown first, in a separate commit, and raises the level after.

The second change checks what the hook cannot: anchors, links written in HTML templates and shortcodes, and the pages that `public/` actually contains. A new `.github/workflows/links.yml` runs on pull requests that touch `content/**`, `layouts/**` or `hugo.toml`, installs Node and the pinned Hugo release read from `netlify.toml`, builds with the same command Netlify uses, and runs `lycheeverse/lychee-action` over `public/**/*.html` in `--offline` mode with `--root-dir public` and `--base-url` set to the site's `baseURL`, failing the job on a broken internal link or fragment. A `lychee.toml` excludes `localhost`, `example.com` and the placeholder hosts the documentation itself uses in examples, and a `.lycheeignore` holds the handful of patterns the agent found while running it.

External links go in a separate job in the same file, on a weekly `schedule` and on `workflow_dispatch`, without `--offline`, with lychee's cache and `accept` list configured so a host that answers 429 to a scanner does not fail the run, and with its Markdown report posted as an issue through `peter-evans/create-issue-from-file` that is updated rather than duplicated. Both jobs get `permissions: contents: read`, the weekly one `issues: write`, actions pinned by SHA with version comments like `lint.yml`, and a `concurrency` group. The agent runs the offline check in its sandbox against the built site, runs the external check once to size the ignore list, and keeps both outputs.

## Start it with one API call

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

```json
{
  "agent": "codex",
  "input": "Add broken link checking to this Hugo site and open a pull request. Read hugo.toml, netlify.toml, package.json, go.mod, hugo.work, .gitignore, AGENTS.md, layouts/_markup/render-link.html, .github/workflows/lint.yml and .markdownlint-cli2.yaml first. Install Hugo extended at the HUGO_VERSION netlify.toml pins, run npm i and hugo --gc --minify, and read the build log for unresolved link destinations from the link render hook; fix any in a separate commit, then raise params.render_hooks.link.errorLevel to error in hugo.toml. Add .github/workflows/links.yml with two jobs: on pull requests touching content, layouts or hugo.toml, build the site with the same Hugo version and command and run lycheeverse/lychee-action over public/**/*.html in --offline mode with --root-dir public and --base-url from baseURL, failing on broken internal links and fragments; and on a weekly schedule and workflow_dispatch, run lychee without --offline over the built site with caching and an accept list for rate-limited hosts, posting the report as a single updated issue with peter-evans/create-issue-from-file. Add lychee.toml and .lycheeignore for localhost, example.com and the placeholder hosts used in the documentation's examples. Pin every action by commit SHA with a version comment as lint.yml does, set least-privilege permissions and a concurrency group. Run the offline check and one external check in the sandbox, and list in the pull request what each found.",
  "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

What comes back is a pull request that adds `.github/workflows/links.yml`, `lychee.toml` and `.lycheeignore`, changes one line of `hugo.toml`, and, when the first build showed unresolved destinations, a separate commit fixing those Markdown links. The description says which Hugo version the workflow installs and where that number is read from, what the offline check found on `public/`, and what the one external run found, host by host, so the ignore list can be reviewed line by line.

The run's record keeps the `hugo --gc --minify` log, the offline lychee output and the external lychee output, so a reviewer can see what the render hook warned about and what lychee found without building the site locally.

Before merging, a reviewer decides whether the weekly issue should go to a label or a project, and whether the pull request job should also run on `push` to `master`, which `lint.yml` does and `links.yml` leaves to them.

## Run it on every documentation site with no link check

A team with several Hugo sites sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `hugo.toml`, so a site with no link render hook gets the offline lychee check as its only internal guard, a site that deploys from GitHub Pages gets the check added to the workflow that already builds it, and a site with a different `publishDir` gets `--root-dir` pointed at that. Each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each run the key started finishes, with `session_url` to read the pull request and the link report from, so the broken links each site already has can be triaged in one place.

## Why run it on Rush?

A link check added without reading the site checks the wrong thing: source Markdown instead of the HTML a visitor gets, external hosts on every pull request until a rate limit turns the job red, or a second tool for a check the render hook already does. In a Rush sandbox the agent installs the pinned Hugo, runs the real build, reads its warnings, and runs lychee against the real `public/`, and every command's output stays in the run, so the pull request shows what was checked and what was found.

The build of a documentation site with a thousand pages, a Tailwind pipeline and an external scan runs on the agent's own machine, not on anyone's laptop, and the same request goes to every site in the org at once. The result is a check that fails for the right reason on the next renamed page.

## Frequently asked questions

### Doesn't Hugo already check links?

Only through a link render hook, and only when the site has one with `errorLevel` set. The hook in `layouts/_markup/render-link.html` resolves Markdown link destinations at build time; it does not check fragments, links in templates or shortcodes, or external hosts. The pull request raises the hook to `error` and adds lychee for the rest.

### Why run the external check weekly instead of on every pull request?

External hosts answer slowly, rate-limit scanners and go down on their own schedule, none of which a pull request author can fix. The offline check on `public/` is deterministic and fast and fails the pull request; the external check runs weekly and reports in an issue that is updated in place.

### Which Hugo version does the workflow use?

The one `netlify.toml` pins in `HUGO_VERSION`, read by a step in the workflow rather than copied, so bumping Netlify bumps CI. The extended build is used because the site's Tailwind pipeline needs it.

### Will it fail on links in generated pages like content/en/commands?

Those pages are built into `public/` like any other and are checked. If one carries a broken link, the fix belongs in the generator that writes them, which `AGENTS.md` says not to edit by hand, so the pull request lists such a case for the maintainers rather than editing the file.

## More Hugo jobs

- [Add llms.txt to a Hugo Docs Site with an Output Format](https://getrush.ai/run/add-llms-txt/hugo/)
- [Add Mermaid Diagrams to a Hugo Docsy Site](https://getrush.ai/run/add-mermaid-diagrams/hugo/)
- [Add Reading Time to a Hugo Blog](https://getrush.ai/run/add-reading-time/hugo/)

## The same job on other stacks

- [Add Link Checking to a Jekyll Site with html-proofer](https://getrush.ai/run/add-link-checking/jekyll/)
- [Add External Link Checking to an mdBook](https://getrush.ai/run/add-link-checking/mdbook/)
- [Add Link Checking to an MkDocs Site](https://getrush.ai/run/add-link-checking/mkdocs/)

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