# Add a Table of Contents to Eleventy Blog Posts

Yes. An agent builds a table of contents from each Eleventy post's headings, using the ids the site already generates, hides it on short posts, and opens a PR.

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

## What the agent does

The agent starts with what the headings already have. In a blog like 11ty/eleventy-base-blog, `eleventy.config.js` registers `IdAttributePlugin`, which gives every `h1` to `h6` in the output an `id` from Eleventy's `slugify` filter, and `_includes/layouts/base.njk` wraps the page content in a `<heading-anchors>` web component from `@zachleat/heading-anchors` so each heading already links to itself. Posts render through `_includes/layouts/post.njk`, which sets the `<h1>` from `title`, prints the `post-metadata` list, then `{{ content | safe }}`. Markdown is processed with Nunjucks as the template engine (`markdownTemplateEngine: "njk"` in the config), and the sample posts show the shapes a contents list must survive: `thirdpost.md` has an `h2`, two `h3` below it, one of them a heading that contains a link, and another `h2` after a code block; `secondpost.md` and `fourthpost.md` have a single `h2`; `fifthpost.md` has none.

It then builds the list from the rendered HTML, so the ids match the ones the plugin wrote. A `toc` filter added to `_config/filters.js`, beside `readableDate`, `head` and `filterTagList`, walks the `h2` and `h3` elements of the post's `content` with `posthtml`, the HTML parser Eleventy 3 itself lists as a dependency, reads each heading's `id` and text with inline markup stripped so the linked heading in `thirdpost.md` becomes plain text, and returns a nested `<ol>` of `<a href="#id">` links. Reading the rendered content rather than the Markdown means a heading written in Nunjucks or HTML inside a post is still found, and the slug logic is never duplicated. The filter returns an empty string when a post has fewer `h2` headings than a threshold the agent sets as a named constant, so `secondpost.md` and `fourthpost.md` show nothing and `fifthpost.md` is untouched.

The layout change is small. `post.njk` gets a `<nav class="toc" aria-label="Contents">` between the metadata list and the content, rendered only when the filter returned something, and `css/index.css` gets a few rules for it next to the existing `.post-metadata` block; because `base.njk` inlines that file into the page bundle, no build setting changes. A post can opt out with `toc: false` in its front matter, and the agent adds that key to the Zod schema in `_data/eleventyDataSchema.js`, where `draft` is already validated, so a typo fails the build instead of silently showing a contents list.

The proof is the built site. The agent runs `npm install` and `npm run build` on the Node 22 that `.nvmrc` pins, then reads `_site/blog/thirdpost/index.html` to show the nested list with its two levels and the link-bearing heading reduced to text, `_site/blog/secondpost/index.html` to show no list on a one-heading post, and checks that each `href` in the list matches an `id` on the same page with a script over the built HTML. The Atom feed and the archive list are left as they are, since neither renders post bodies in a way that wants a contents list.

## 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 blog posts of this Eleventy site. Read eleventy.config.js, _config/filters.js, _data/eleventyDataSchema.js, _includes/layouts/base.njk, _includes/layouts/post.njk, css/index.css and every post under content/blog first, and note that IdAttributePlugin already gives headings ids. Add a toc filter in _config/filters.js that walks the h2 and h3 elements of the rendered content, reads their ids and plain text, and returns a nested ordered list of in-page links, or an empty string when the post has fewer h2 headings than a named threshold. Render it in post.njk inside a nav with an aria-label, only when non-empty, with a few CSS rules beside the existing post-metadata styles. Support toc: false in front matter and validate that key in eleventyDataSchema.js. Do not change any post. Run npm install and npm run build, quote the rendered list for the post with the most headings and show a one-heading post has none, check every link in the list resolves to an id on the same page, 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

What comes back is a pull request on its own branch that touches `_config/filters.js` (the `toc` filter and its threshold constant), `_includes/layouts/post.njk` (the `nav`), `css/index.css` (the rules) and `_data/eleventyDataSchema.js` (the `toc` key). No post, no plugin setting and no dependency changes, since the `posthtml` parser the filter uses is already installed as a dependency of Eleventy itself.

The description quotes the rendered contents list from the post with the most headings and the empty result from a post with one, plus the output of the link check, so a reviewer sees the nesting and the stripped link text without building anything. The build log and every command are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer sets the threshold they want, decides whether `h3` headings belong in the list or only `h2`, and whether the list should sit above or below the metadata. A follow-up message to the same session can make the list collapsible with a `<details>` element, or add a `toc: true` override for a post below the threshold.

## Run it on every Linear issue labelled content

A team that tracks site work in Linear starts one run per issue from an automation with a `linear` trigger on the `content` label, in the Project that holds the blog repository. The automation adds the issue after this prompt, so an issue that asks for a different threshold or for `h4` headings as well is what the agent reads.

Each run builds in its own sandbox and opens its own pull request that links the issue, and an automation run has its own `max_runs_per_hour` cap. The rendered list in the description is what a reviewer reads first.

## Why run it on Rush?

A contents list is easy to get subtly wrong: ids that disagree with the headings' real ids, a heading with a link inside turning into nested anchors, a list that appears on a post with one section. The agent reads the id plugin and the layout chain, builds the list from the rendered HTML so the ids are the real ones, and checks every link against the built page, in a sandbox with the pinned Node and the lockfile's packages.

The pull request carries the rendered list and the link check, so the review is a read of one filter, one `nav` and a few CSS rules. Several blogs built from the same starter can be handled at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Why read the rendered HTML instead of the Markdown headings?

Because the ids come from `IdAttributePlugin` at render time, and a list built from Markdown would have to reproduce its slug rules exactly, including how it handles a heading that contains a link or a duplicate title. Reading the output means the `href` is always the `id` the plugin wrote.

### Will short posts get a contents list?

No. The filter returns an empty string when a post has fewer `h2` headings than a named threshold, so one-section posts render nothing extra. The threshold is one constant in `_config/filters.js`, and a post can also set `toc: false` in its front matter.

### Does it add a dependency?

No. `posthtml`, the HTML parser the filter uses, is already in `node_modules` as a dependency of `@11ty/eleventy` 3, so the filter imports it rather than adding a new package. The pull request names the import so a reviewer can check it.

### What happens to a heading that contains a link?

Its text is used and its inline markup dropped, so the list entry is a single link to the heading rather than a link inside a link. The sample post with such a heading is the one the pull request quotes, so a reviewer sees that case rendered.

## More Eleventy jobs

- [Add a Typo Check to an Eleventy Blog in CI](https://getrush.ai/run/add-typo-check/eleventy/)
- [Add Webmentions to an Eleventy Blog](https://getrush.ai/run/add-webmentions/eleventy/)
- [Dockerize an Eleventy Site](https://getrush.ai/run/dockerize-app/eleventy/)

## The same job on other stacks

- [Add a Table of Contents to Gatsby Blog Posts from a Linear Issue](https://getrush.ai/run/add-table-of-contents/gatsby/)
- [Add a Table of Contents to a Hugo Blog](https://getrush.ai/run/add-table-of-contents/hugo/)
- [Add a Table of Contents to Jekyll Posts](https://getrush.ai/run/add-table-of-contents/jekyll/)

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