All jobs

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

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

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading