All jobs

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 RushOpens 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 with this body:

{
  "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.

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

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

The same job on other stacks

Keep reading