# Add a Table of Contents to Zola Posts

Yes. An agent adds a table of contents to the posts of a Zola site from the page.toc variable, opt-in per post, styled with the theme's Sass, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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 `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`.

## 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.

## More Zola jobs

- [Add a Typo Check to a Zola Site](https://getrush.ai/run/add-typo-check/zola/)
- [Add a Build Check for Every Pull Request to a Zola Site](https://getrush.ai/run/add-build-check/zola/)
- [Add Dark Mode to a Zola Theme](https://getrush.ai/run/add-dark-mode/zola/)

## The same job on other stacks

- [Add a Table of Contents to an Astro Blog](https://getrush.ai/run/add-table-of-contents/astro/)
- [Add a Table of Contents to Eleventy Blog Posts](https://getrush.ai/run/add-table-of-contents/eleventy/)
- [Add a Table of Contents to Gatsby Blog Posts from a Linear Issue](https://getrush.ai/run/add-table-of-contents/gatsby/)

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