All jobs

Add llms.txt to a Zola Site With a Feed Template

Yes. An agent makes Zola write llms.txt at build time by naming it as a feed with its own template, checks the file against the built site, 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

Zola has no plugin system, so the agent looks for a built-in that already writes a text file from every page before it reaches for a script. In a site built on the getzola/even theme, config.toml sets base_url to https://getzola.github.io/even/, compile_sass = true, generate_feed = true, two taxonomies categories and tags with feed = true each, and highlight_code = true with the css highlight theme. content/_index.md sets paginate_by = 5 and sort_by = "date", the posts sit directly under content/ as first_post.md through tenth_post.md plus some-article.md, markdown_overview.md and Theme_Overview.md, each with TOML front matter carrying title, date and [taxonomies], and content/pages/ holds an about.md under a section with render = false. templates/index.html is the base layout; it already loops over config.feed_filenames to emit <link rel="alternate"> tags when config.generate_feeds is set, which is the plural spelling Zola uses from 0.19 on, while the demo config still has the singular key, and theme.toml says min_version = "0.17.0". .github/workflows/docs.yml builds and deploys with shalzz/zola-deploy-action@v0.17.2 on pushes to master.

The built-in is the feed. Zola writes one file per name in feed_filenames, and for a name that is not atom.xml or rss.xml it renders templates/<that name> with config, feed_url, last_updated, lang and pages, every page that has a date and include_in_feeds left true. So the agent sets generate_feeds = true and feed_filenames = ["atom.xml", "llms.txt"], which keeps the Atom feed the theme's templates and readers already expect, and writes templates/llms.txt in Tera: an # {{ config.title }} line, a > {{ config.description }} quote, a ## Posts list of - [{{ page.title }}]({{ page.permalink | safe }}): {{ page.description or summary }} entries, and a ## Pages list built with get_section(path="pages/_index.md") so the undated About page, which the feed variable leaves out, still appears. Dates are not in the feed order the spec wants, so the template sorts nothing and relies on pages arriving newest first as the Atom template does. A second file, llms-full.txt, goes into the same list with a template that writes each post's {{ page.content | striptags }} under its heading, and the agent checks that the KaTeX shortcode in templates/shortcodes/katex.html has rendered to text rather than leaking raw braces into it.

Two consequences need handling. The base template's <link rel="alternate"> loop now runs over three filenames and would advertise llms.txt as a feed with an RSS media type, so the agent adds {% if feed is ending_with(".xml") %} around the tag, and the taxonomy templates under templates/tags/ and templates/categories/ inherit no such loop and need no change. Second, taxonomies with feed = true get their own feed files per term; Zola renders those from the same filenames, so a tag page would also get a llms.txt. The agent keeps feed = true on the taxonomies and notes in the pull request that per-tag llms.txt files are generated, with the one-line change that drops them if the team would rather not, since removing the setting also removes the per-tag Atom feeds the theme links to.

Then it builds. In its own sandbox the agent installs a Zola release that has the plural feed keys, 0.19 or newer, since the 0.17.2 release the deploy action pins knows only generate_feed and feed_filename and would write no llms.txt, moves shalzz/zola-deploy-action in docs.yml to that release, runs zola build, and reads public/llms.txt and public/llms-full.txt: every post permalink begins with the configured base_url, the About page is present once, the summaries match the <!-- more --> cut the posts use, and no Tera syntax or HTML tag survives in the full file. zola check runs too, because it fetches external links in content and the file now points at every page. The agent also builds with --base-url http://127.0.0.1:1111 the way zola serve does, to confirm the permalinks follow the flag rather than being hard-coded, and keeps both outputs in the run's record.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add an llms.txt and an llms-full.txt to this Zola site using Zola's feed mechanism rather than a script. Read config.toml, theme.toml, templates/index.html, the taxonomy templates, content/_index.md, the front matter of every page under content and the GitHub workflow first. Set generate_feeds and add both filenames to feed_filenames while keeping atom.xml. Write templates/llms.txt with the site title and description, a list of every dated page as a Markdown link with its description or summary, and the undated pages from the pages section through get_section. Write templates/llms-full.txt with each page's rendered content stripped of HTML. Keep the alternate-link loop in the base template from advertising the text files as feeds. Say in the pull request what happens to taxonomy feeds and how to opt out. Install a Zola release that has generate_feeds and feed_filenames, 0.19 or newer, move the deploy workflow's zola-deploy-action to the same release, run zola build and zola check, read the two generated files back and quote them, build once more with a different --base-url to confirm the permalinks follow it, and open a pull request.",
  "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

A pull request that changes config.toml, adds templates/llms.txt and templates/llms-full.txt, edits one loop in templates/index.html, and moves docs.yml to the Zola release the plural feed keys need. The description quotes the generated public/llms.txt in full from the sandbox build, the first entries of public/llms-full.txt, and the zola check summary, so a reviewer reads the file a model would read without checking out the branch.

The docs.yml workflow runs only on pushes to master, so the pull request has no check of its own; the build output in the run's record is the evidence until the merge deploys it, and the description names a pull-request build as the next change if the team wants one. Before merging, a reviewer decides whether the per-tag copies the taxonomy feeds produce should stay, and whether the full file should include drafts, which it does not.

Run it on every Zola site you maintain

A team with several Zola 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. Each run reads its own config, so a site that already lists rss.xml keeps it, a site with sections under content/ gets a ## <Section> block per section from get_section, and a multilingual site gets one file per language, which Zola writes beside each language's feed.

After the merge, the file stays current without another run because Zola rebuilds it on every deploy. A github trigger on pull_request.opened with the prompt "if this pull request adds a page with no date or with include_in_feeds false, say in a comment that it will be missing from llms.txt" catches the one case the template cannot see.

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

Why run it on Rush?

Writing llms.txt by hand goes stale with the next post, and a script in CI is a second build that has to agree with Zola about permalinks, summaries and drafts. Using the feed templates makes Zola the only thing that knows the page list, and the only honest check is the built public/ directory: the right pages, the configured base_url, no template syntax in the full file, and no new alternate link in every page's head. The agent builds the site in its own sandbox with the pinned release and reads the files back before it opens the pull request.

Every command stays with the run, from the Zola install to the second build with another base URL, and the pull request quotes the files. The same change across a dozen Zola sites costs no more attention than one, because each run has its own machine and its own pull request.

Frequently asked questions

Why a feed template instead of a file in static/?

A file under static/ is copied as it is, so it lists whatever was true when someone last edited it. A feed template is rendered on every build from the same page collection as the Atom feed, with the permalinks Zola computes from base_url, so a new post or a renamed slug is in the file the moment the site is.

Does this break the existing Atom feed?

No. atom.xml stays first in feed_filenames and is still rendered by Zola's built-in template, and the theme's alternate link to it is unchanged. The one edit to the base template keeps the two new text files out of that <link rel="alternate"> loop.

Which pages are missing from the file?

Pages with no date, pages with include_in_feeds = false, and drafts, because the feed variable Zola hands the template leaves them out. The template adds the undated pages of the pages section back through get_section; any other undated page needs a date or a line in that block, and the pull request says so.

Why do the tag pages get an llms.txt too?

Because both taxonomies have feed = true, and Zola renders every name in feed_filenames for each term. The pull request leaves that on, since turning it off also removes the per-tag Atom feeds the theme links to, and shows the one setting to change if the copies are unwanted.

More Zola jobs

The same job on other stacks

Keep reading