# Add a Table of Contents to Jekyll Posts

Yes. An agent adds a plugin-free Liquid table of contents to your Jekyll post layout, turned on per post with toc: true, builds both Jekyll majors, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-table-of-contents/jekyll/). 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 before it adds to it. In a site laid out like daattali/beautiful-jekyll, `_config.yml` sets `markdown: kramdown` with `input: GFM`, lists `jekyll-paginate` and `jekyll-sitemap` as the only plugins, and gives posts the `post` layout through `defaults`. `_layouts/post.html` includes `header.html` with `type="post"`, which prints the author, date, `last-updated` and, when a post sets `readtime`, the `readtime.html` include; the body is `{{ content }}` inside `div.blog-post`, with optional `before-content` and `after-content` includes around it. The gemspec pins `jekyll >= 3.9.3`, and `Appraisals` builds against 3.9.4 and 4.3.3, which `.github/workflows/ci.yml` runs on Ruby 3.3 with `bundle exec appraisal jekyll build --future`. `_posts/2020-02-28-sample-markdown.md` has `##` and `###` headings and one with an explicit id, `## Local URLs in project sites {#local-urls}`. Nothing in `_includes` or `assets/js/beautifuljekyll.js` builds a table of contents.

Because the theme is used by sites that build on GitHub Pages, where only an allowed set of plugins loads, the agent writes the table of contents in Liquid rather than as a gem. `_includes/toc.html` takes the rendered `content`, splits it on `<h` tags, keeps the levels between `h_min` and `h_max`, reads each heading's `id`, which kramdown generates automatically and which the sample post's `{#local-urls}` overrides, strips the inner HTML for the link text, and emits a nested `<ul>` of anchor links. It handles a level that jumps from `h2` to `h4` without an unclosed list, and a heading with no id is skipped rather than linked nowhere.

`_layouts/post.html` gains `{% if page.toc %}{% include toc.html html=content h_min=2 h_max=3 %}{% endif %}` just above `div.blog-post`, so a post opts in with `toc: true` in its front matter and a site opts every post in with one more line under the posts entry in `defaults`. The `page` layout gets the same lines, since it already mirrors `post.html`'s `before-content` and `after-content` handling. Styles go in `assets/css/beautifuljekyll.css` next to the `.post-meta` rules, using the theme's existing font and link colours so the block reads as part of the page in both the default palette and a site's own `navbar-col`-style overrides.

The sample post gets `toc: true` so the demo site shows the feature, the README's list of post front matter parameters documents the new key beside `readtime`, and `CHANGELOG.md` gets an entry. The agent then runs `bundle install`, `bundle exec appraisal install` and `bundle exec appraisal jekyll build --future`, so the include is proven on Jekyll 3.9.4 and 4.3.3, and reads the generated HTML for the sample post to confirm every link's `href` matches a heading id in the same file. It also notes in the pull request that kramdown's own `* TOC` with `{:toc}` still works inside a post for anyone who wants the list at a specific spot, since the include does not interfere with it.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add an optional table of contents to blog posts in this Jekyll theme. Read _config.yml, _layouts/post.html, _layouts/page.html, _includes/header.html, _includes/readtime.html, _posts/2020-02-28-sample-markdown.md, assets/css/beautifuljekyll.css, beautiful-jekyll-theme.gemspec, Appraisals and .github/workflows/ci.yml first. Write _includes/toc.html in pure Liquid, no plugin, that reads the rendered content, collects h2 and h3 headings with their kramdown ids, and renders a nested list of anchor links; skip headings without an id. Include it in the post and page layouts only when page.toc is true, add CSS beside the .post-meta rules, set toc: true on the sample post, document the parameter in the README and CHANGELOG, and build the site with bundle exec appraisal jekyll build --future on both Jekyll versions. Check that every generated link targets a heading id on the same page, then open a pull request that quotes the build 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 adds `_includes/toc.html`, changes `_layouts/post.html` and `_layouts/page.html` (the conditional include), `assets/css/beautifuljekyll.css` (the styles), `_posts/2020-02-28-sample-markdown.md` (`toc: true`), the README (the parameter) and `CHANGELOG.md`. Its description quotes both appraisal builds and shows the rendered list for the sample post with its `#local-urls` link.

A reviewer opens the built sample post, clicks each entry, and then reads the include for the cases Liquid makes awkward: a heading that contains a link or inline code, a heading with the same text twice, and a page whose first heading is an `h3`. They also decide whether the default should be off, as implemented, or on for every post through `defaults`.

Nothing changes for a post without `toc`, and the HTML of such a post is byte for byte the same as before, which the build output lets the reviewer check.

## Run it on every new theme release

A maintainer who keeps several sites on this theme starts one run per site from their own machine or server, each `POST /o/{org}/sessions` naming that site's repository in `resources` with a `request_id` that is a UUID v5 of the repository name, so a repeated call returns the run already started. Each run reads that site's `_config.yml` and layouts, which often override the theme's, and places the include where that site's post layout puts its content.

An automation on the Project with a `schedule` trigger set to `1d` can read the site read-only each night, build it, and comment when a post's headings produce a link that targets no id, for instance after a heading is renamed; it comments and pushes nothing, so the fix is a run started as above.

## Why run it on Rush?

Liquid has no debugger, and the only proof an include works is a built site. The agent installs both Jekyll versions the theme supports, builds with each in its own sandbox, reads the output HTML, and keeps the build logs with the pull request, so the reviewer sees the include working on 3.9.4 and 4.3.3 rather than taking the template on trust.

The include is written for this theme's layouts, its kramdown settings and its demo post, not for Jekyll in general. A team with several Jekyll sites starts the same request against each one at once and gets a pull request per site, each fitted to that site's own layouts.

## Frequently asked questions

### Does this work on GitHub Pages?

Yes. The include is Liquid and HTML, so it needs no plugin and no change to the plugin list. Sites that use the theme through `remote_theme` get it with the theme, and sites that copy the layouts add one include and two lines.

### Why not the jekyll-toc gem or kramdown's {:toc}?

A gem does not load on GitHub Pages unless it is on the allowed list. Kramdown's `{:toc}` works, but only from inside a post's markdown, so a layout cannot switch it on for every post. The include is controlled from front matter and defaults, and `{:toc}` keeps working beside it.

### Which headings are included?

`h2` and `h3` by default, set through the `h_min` and `h_max` parameters on the include. The post title is an `h1` in the header and is left out. A heading without an id is skipped, so nothing links to an anchor that does not exist.

### Can a single post turn it off when the site default is on?

Yes. `toc: false` in that post's front matter overrides the `defaults` entry in `_config.yml`, the same way `comments` and `social-share` already work per post.

### Where does the list appear?

Above the post body, under the header, inside the same column as the content. Moving it into the `before-content` include list or beside the body is a one-line change in `post.html` that the pull request describes.

## More Jekyll jobs

- [Add Tag Pages to a Jekyll Blog](https://getrush.ai/run/add-tag-pages/jekyll/)
- [Add a Typo Check to a Jekyll Site in CI](https://getrush.ai/run/add-typo-check/jekyll/)
- [Add Author Pages to a Jekyll Blog](https://getrush.ai/run/add-author-pages/jekyll/)

## The same job on other stacks

- [Add a Table of Contents to mdBook Chapters](https://getrush.ai/run/add-table-of-contents/mdbook/)
- [Add a Table of Contents to Zola Posts](https://getrush.ai/run/add-table-of-contents/zola/)
- [Add a Table of Contents to an Astro Blog](https://getrush.ai/run/add-table-of-contents/astro/)

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