All jobs

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

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading