# Add llms.txt to a Hugo Docs Site with an Output Format

Yes. An agent adds Hugo output formats that render llms.txt and llms-full.txt from your docs at build time, like your site's _redirects file, and opens a PR.

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

## What the agent does

Hugo can write any text file from a template, so the agent looks for a place where the site already does that before adding a tool. In a site like jaegertracing/documentation, `hugo.yaml` sets `baseURL` to `https://www.jaegertracing.io`, stacks three themes (`docsy-overrides`, `docsy`, `basetheme`), and declares a custom media type `text/netlify` with an output format `REDIRECTS` whose `baseName` is `_redirects` and which is `notAlternative: true`. `outputs.home` is `[HTML, REDIRECTS]` and `outputs.section` is `[HTML]`, with a comment explaining that JSON output was removed because nothing consumed `/index.json` and listing it only made the home page advertise an alternate link that answered 404. `layouts/index.redirects` is the template for that format: it collects lines from `layouts/_partials/redirects.txt`, which ranges over `site.Params.versions` and the pages under the latest docs section, sorts them and warns on duplicates. That is exactly the shape an `llms.txt` needs.

The docs live under `content/docs/v2/<version>/`, one directory per release from `2.0` to `2.22` plus `_dev`, with `site.Params.latestV2` set to `2.22` and `versionsV2` listing them all; v1 docs sit under `content/docs/v1/` with `latest` at `1.76`. The `2.22` tree has 32 Markdown files: `getting-started.md`, `features.md`, `faq.md` and the `architecture`, `deployment`, `operations`, `storage` and `external-guides` sections, with an `_index.md` that sets `sidebar_root_for: self` and cascades `robots: true`. Across all of `content/` there are 748 Markdown files, 708 of them under `v2`, so a file that listed every version would be mostly duplicates. `enableGitInfo` is on. `package.json` names `hugo-extended` 0.166.0 as a peer dependency, builds with `hugo --cleanDestinationDir --config hugo.yaml` through the `_hugo` script and `--minify` for production, and `netlify.toml` publishes `public`. `hugo.dev.yaml`, used by `npm run build`, ignores older version directories to keep local builds short.

The agent adds two output formats to `hugo.yaml`: `LLMS` with `mediaType: text/plain`, `baseName: llms`, `isPlainText: true` and `notAlternative: true`, and `LLMSFULL` with `baseName: llms-full`, and extends `outputs.home` to `[HTML, REDIRECTS, LLMS, LLMSFULL]`; sections keep HTML only. `notAlternative` keeps Docsy's head partial from printing a `<link rel="alternate">` for the new formats, the same reason the JSON output was dropped. `layouts/index.llms.txt` prints `# ` and `site.Title`, a `> ` line with `site.Params.tagline`, then a `## Docs` section built from `site.GetPage` on `/docs/<latestV2>` and its `RegularPagesRecursive` sorted by weight, one `- [title](permalink): description` line each, with the description falling back to the page summary through `plainify`, and a final section pointing at the `_index.md` of the latest v1 docs and the `versionsV2` list. `layouts/index.llmsfull.txt` ranges over the same pages and writes each one's title as a heading followed by `.Plain`, the rendered content with HTML stripped, so shortcodes such as the admonitions render as text rather than as `{{< info >}}` syntax.

Then the agent builds and runs the site's own checks. `npm install` brings in `hugo-extended` and the pinned Docsy commit, `npm run build:production` writes `public/llms.txt` and `public/llms-full.txt`, and the agent counts the links in the first against the 32 pages under `2.22`, checks that every link starts with the `baseURL`, and reads the head of the second to confirm no raw shortcode syntax or HTML tags survived. It runs `npm run check:links:internal`, which rebuilds and runs `htmltest` over `public` with `--skip-external`, `npm run check:spelling`, which is `cspell` over `content` and the Markdown under `layouts`, and `npm run check:format`, which is `prettier --check .`; a `.txt` template is outside all three, which the pull request says. The `_headers` and CSP in `netlify.toml` apply to every path and are left alone.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add llms.txt and llms-full.txt to this Hugo site as output formats. Read hugo.yaml, hugo.dev.yaml, package.json, netlify.toml, the Makefile, layouts/index.redirects and layouts/_partials/redirects.txt first, and find how the site already renders its _redirects file from a template. Add two output formats in hugo.yaml, LLMS with baseName llms and LLMSFULL with baseName llms-full, both text/plain, isPlainText and notAlternative, and add them to the home page outputs only. Write layouts/index.llms.txt with the site title, the tagline, one link line per regular page under the latest v2 docs version sorted by weight with the page description or summary, and a short section naming the other documented versions. Write layouts/index.llmsfull.txt with each of those pages' title and plain-text content. Run npm install and npm run build:production, count the links in public/llms.txt against the pages in that version, check every link uses the baseURL, and check public/llms-full.txt for leftover HTML or shortcode syntax. Run npm run check:links:internal, npm run check:spelling and npm run check:format. Open a pull request that shows the head of the generated llms.txt.",
  "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 `hugo.yaml` and adds `layouts/index.llms.txt` and `layouts/index.llmsfull.txt`, three files. Its description shows the first lines of the generated `llms.txt`, the link count, and the exact `outputs.home` line, so a reviewer can see the home page is the only page that gained formats.

The `Test` workflow runs on the pull request: `build-and-check-links` builds the site and runs `htmltest` over every HTML page, and `spellcheck` runs `cspell` over the content. Neither reads a `.txt` output, so the run's record, with the build log and the head of both generated files, is the proof that the templates render.

Before merging, a reviewer decides whether older v2 versions deserve their own entries or only a mention, whether the v1 docs belong in the file at all now that `1.76` is the last of that line, and whether the `llms-full.txt` should carry the whole 32-page body or a subset such as `getting-started` and `architecture`, since `.Plain` includes every rendered word of every page.

## Run it on every Hugo documentation site you maintain

An organization with several Hugo sites starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with this prompt as `input`, the 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 the repositories the Rush GitHub App installation reaches, so the script can pick the ones with a `hugo.yaml` or `hugo.toml` and no `llms` output format. Each run reads its own config, so a site whose docs are one section rather than one directory per version gets a template that ranges over that section, and a site built with a `config/` directory gets the formats added there.

A team that tracks site work in Linear runs the same prompt from an automation in the Project with a `linear` trigger on issues labelled `website`. The trigger adds the issue after the prompt, so an issue that asks for the file to cover only the getting-started pages, or to list every version, reaches the agent with that instruction, and the pull request links back to it.

## Why run it on Rush?

Two output formats and two templates are a small change, but whether they are right shows only in the built `public/` directory: the right pages, the right `baseURL`, no shortcode syntax in the full file, and no new alternate link in every page's head. The agent builds the site in its own sandbox on the Hugo version `package.json` names and keeps the generated files with the run, so a reviewer reads the actual `llms.txt` rather than a promise of one.

The site's own checks, `htmltest`, `cspell` and `prettier`, run in the same sandbox before the pull request opens, and the same prompt runs across every Hugo site in the organization at once, each in its own sandbox with its own pull request and its own build log.

## Frequently asked questions

### Why an output format instead of a file in static/?

A static file lists the pages someone remembered on the day it was written. An output format is rendered from the same page tree as the HTML, so a page added to the latest docs directory appears in `llms.txt` on the next build, and the site already uses this mechanism for `_redirects`, so maintainers know how it works.

### Does it include every documented version?

The link section covers the latest v2 version only, which is what `site.Params.latestV2` names, and older versions are mentioned in one short section. Listing all 708 v2 pages would repeat the same titles once per release; a site that wants a file per version can add the formats to its section outputs and give the version directories their own templates.

### Will Docsy add a link tag for the new format to every page?

No. Both formats are declared `notAlternative: true`, so they do not appear in a page's `AlternativeOutputFormats` and the head partial prints no `rel="alternate"` for them. The config comment about the removed JSON output describes exactly the problem this flag avoids.

### Do the spell check and link check cover the new templates?

`cspell` runs over `content` and the Markdown files under `layouts`, and `htmltest` reads the HTML under `public`, so a `.txt` template and its output are outside both. The agent reads the generated files itself and the pull request says so, so a maintainer who wants `llms.txt` spellchecked knows to extend the `cspell` paths.

### What does llms-full.txt contain?

The title and `.Plain` content of each page in the latest v2 docs: the rendered text with HTML removed, so admonition and version shortcodes appear as their text rather than their template syntax. It is the file an assistant reads when it needs the pages themselves and not only their addresses.

## More Hugo jobs

- [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/)
- [Add Related Posts to a Hugo Blog](https://getrush.ai/run/add-related-posts/hugo/)

## The same job on other stacks

- [Add llms.txt to a Jekyll Site](https://getrush.ai/run/add-llms-txt/jekyll/)
- [Add llms.txt to an mdBook Site](https://getrush.ai/run/add-llms-txt/mdbook/)
- [Add llms.txt to a MkDocs Site](https://getrush.ai/run/add-llms-txt/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/)
