What the agent does
The agent reads the theme's templates and content before it changes a post's layout. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, templates/page.html extends templates/index.html and fills the content block with three macros from templates/macros/post.html: post_macros::header, which prints the title, date and tags, post_macros::content with the full text, and post_macros::earlier_later, which renders the previous and next post links when config.extra.enable_post_view_navigation is on. The posts in content/ are short; welcome-terminimal-theme.md is the one with headings, four levels from # Header 1 to #### Header 4 plus a ## Shortcodes section, and it is the page the agent uses to check the result. content/_index.md sets paginate_by = 2 and sort_by = "date" for the post list, and sass/style.scss imports the theme's partial stylesheets, buttons, header, logo, main, post, pagination and footer, which compile_sass = true in config.toml builds.
Zola builds the table of contents itself. Every page carries a toc variable, an array of headers with level, id, permalink, title and children, and the Zola docs render it with a loop over page.toc and a nested loop over h1.children. Heading ids exist whether or not anchors are shown; insert_anchor_links in a section's front matter, with left, right, heading or none as values and none as the default, adds the visible anchor links next to each heading. The theme uses h1 for the post title, so content headings at level one would sit beside it in the list, which is why the macro renders what the author wrote rather than filtering by level.
The agent adds a toc macro to templates/macros/post.html that renders nothing when page.toc is empty, and otherwise a nav with the class toc, a small heading from config.extra.toc_title, and nested ul lists three levels deep, each item linking h.permalink with h.title, following the structure in the docs. page.html calls it between the header and the content, guarded so a post shows the list only when its front matter sets toc = true under [extra], or when config.extra.toc turns it on for every post and the front matter does not set it to false. config.toml gets commented toc and toc_title entries under [extra], welcome-terminimal-theme.md gets toc = true so the demo site shows the feature, and content/_index.md gets insert_anchor_links = "left" so the headings the list points at carry a visible anchor. A new sass/toc.scss, imported from style.scss after post, styles the block with the theme's --accent and --accent-alpha-70 variables and the dashed border the post title already uses.
Then the agent builds and looks. It installs the Linux build from the v0.23.6 Zola release, the current one, runs zola build and zola check at the theme's root, where config.toml and content/ make it its own demo site, confirms that public/welcome-terminimal-theme/index.html holds the list with links to #header-2, #header-3 and #shortcodes, and that public/zola-is-nice/index.html, which has no headings and no toc flag, is unchanged. It serves public/ and opens the post in its own browser to see the block sit between the tags and the first paragraph in each of the theme's colour schemes. A README section under Configuration explains the two settings and the front matter key.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a table of contents to the posts of this Zola site. Read config.toml, templates/index.html, templates/page.html, templates/macros/post.html, every file under content/ and sass/, and the README first. Add a toc macro to templates/macros/post.html that renders nested lists from page.toc, three levels deep, linking each heading's permalink and title, with a title from config.extra.toc_title, and nothing when the page has no headings. Call it from page.html between the post header and the content, shown when the post sets toc = true in its extra front matter or when config.extra.toc is true and the post does not set it to false. Add commented toc and toc_title entries to config.toml, set toc = true on the post that has headings, set insert_anchor_links to left in content/_index.md, and add sass/toc.scss imported from style.scss using the theme's accent variables. Install Zola, run zola build and zola check, confirm the list appears on that post and on no other page, serve the site and open the post in the browser. Add a README section. Open a pull request with the commands and their output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 templates/macros/post.html, templates/page.html, config.toml, content/_index.md, content/welcome-terminimal-theme.md, sass/style.scss and the README, and adds sass/toc.scss. Its description quotes the zola build and zola check output, shows the rendered list for the demo post with the heading ids it links, names the pages whose HTML did not change, and includes a screenshot of the block in the default blue scheme.
A reviewer checks whether the list should be on by default through config.extra.toc or opt-in per post, whether three levels is the right depth for the site's longest posts, and whether anchor links should be on the left, on the right or on the heading itself. Each is one value in config.toml or _index.md.
Run it on every new blog repository
A server that provisions sites for a team sends this body once per repository, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried start returns the run already started. The API key's webhook_url reports each run as it ends, with the pull request's address in the session, and the person who owns the site reviews it from the console.
A site with more than one section of long posts gets one run per section, each setting insert_anchor_links in that section's _index.md.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Where the list sits in the theme's block structure and which headings it links are questions the built site answers. The agent installs Zola in its own sandbox, builds, reads the generated HTML for the post with headings and for the posts without, opens the page in a browser and keeps every command and its output in the run's record, so the pull request shows the list exactly as a visitor sees it.
The change respects the theme as written: the macros file every post template already imports, the config.extra pattern behind the navigation prompt, the Sass partial list in style.scss and the accent variables the colour schemes define. Ten sites on ten Zola themes get ten pull requests, each placing the list in that theme's own post template.
Frequently asked questions
Do I need a plugin for this?
No. Zola builds the toc array for every page from its Markdown headings, and the macro only renders it. There is no extension to install and no JavaScript on the page.
Will every post get a table of contents?
Only the posts that ask for one. By default the macro renders for a post whose front matter sets toc = true under [extra]; setting toc = true under [extra] in config.toml turns it on for every post, and a post can still set toc = false to opt out. A post with no headings renders nothing either way.
Why change insert_anchor_links?
The list's links work without it, because Zola gives every heading an id. insert_anchor_links = "left" in content/_index.md adds a visible anchor next to each heading so a reader who arrives from the list can copy the link to that section; the pull request names right, heading and none as the alternatives.
How deep does the list go?
Three levels, which covers the demo post's h2, h3 and h4 headings under its h1. The macro's nested loops follow the shape in the Zola docs, and a site that wants fewer levels removes the innermost loop.