All jobs

Add a Table of Contents to a Hugo Blog

Yes. An agent renders Hugo's built-in table of contents on your posts behind a front matter flag, styles it in the theme's CSS, builds the demo site 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 how posts are rendered before it adds anything, because Hugo already builds the table of contents and the theme decides where it goes. In a site on janraasch/hugo-bearblog, layouts/_default/baseof.html defines the page skeleton with a main block and pulls partials/style.html, which is the theme's whole stylesheet as one inline <style> element with CSS variables for colours and a prefers-color-scheme: dark override; there is no Sass and no static CSS file. layouts/_default/single.html fills main for a post: when .Type is blog and the page is not a menu entry it prints the <h1>, a <time> with the date in the format .Site.Params.dateFormat chooses, then .Content inside a custom <content> element and partials/post_footer.html for the tags and the optional post navigator. Nothing in the tree mentions TableOfContents, and exampleSite/hugo.toml has a [markup.highlight] table but no [markup.tableOfContents], so Hugo's defaults apply: headings from level 2 to level 3, as an unordered list. theme.toml sets min_version = "v0.110.0", archetypes/blog.md is the front matter a new post starts from, and package.json has one script, npm run beautify, which runs js-beautify over layouts/**/*.html in place with the settings in .jsbeautifyrc.

The change is small and opt-in. In single.html, between the date and <content>, the agent adds {{ if and (eq .Type "blog") (.Param "toc") }} around {{ .TableOfContents }}, so a post turns it on with toc = true in its front matter and a site turns it on everywhere with toc = true under [params] in hugo.toml, which is what .Param falls back to. Hugo emits the list inside <nav id="TableOfContents">, so the agent adds a rule for that id to partials/style.html that uses the existing --text-color and --link-color variables, drops the bullet markers and tightens the line height, and does the same for the nested list, so it reads as a list of links in both colour schemes without any new variable. archetypes/blog.md gains a commented toc = true line under the commented description, so the next hugo new blog/... shows the switch, and the README's configuration section gets a short paragraph naming the page param, the site param and the [markup.tableOfContents] keys startLevel, endLevel and ordered.

The example site is the proof. exampleSite/content/blog/markdown-syntax.md is the one post with headings, and its sections use ## for the sections and #### for the sub-sections, so with Hugo's defaults the table lists its seven ## headings and the one ### H3 from its headings demo, and none of the ten #### sub-section headings; the agent sets toc = true on that post and adds [markup.tableOfContents] with endLevel = 4 to exampleSite/hugo.toml so the sample shows nesting. bear.md and hugo.md have a single # heading each and no toc switch, so they stay as they are, and the agent checks that a post with the switch on and no level 2 or 3 headings renders an empty <nav> or none, and wraps the call in {{ with .TableOfContents }} if it finds the empty element.

The sandbox has no Hugo, so the agent downloads the hugo_0.169.0_linux-amd64.tar.gz asset of the current release from GitHub and builds the way .github/workflows/ci.yml does: hugo --minify --gc --destination ../public --source ./exampleSite --themesDir ../.., with the workflow's --baseURL. It reads public/markdown-syntax/index.html for the <nav id="TableOfContents"> element and counts its links, confirms public/bear/index.html has no such element, serves public on a local port and opens the post in its own browser in light mode and with the dark scheme emulated. It runs npm ci and npm run beautify, then git diff --exit-code layouts to show the formatter changed nothing, since CI does not run it and a hand-edited template is the usual way to drift.

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 Hugo site. Read theme.toml, exampleSite/hugo.toml, layouts/_default/baseof.html, layouts/_default/single.html, layouts/partials/style.html, layouts/partials/post_footer.html, archetypes/blog.md, package.json, .jsbeautifyrc, .github/workflows/ci.yml and the content under exampleSite first. In single.html render .TableOfContents for blog posts only when the toc param is true, read with .Param so a site-wide params.toc works too, and leave the markup out when the page has no headings in range. Style the nav#TableOfContents in style.html with the existing CSS variables so it works in the dark scheme. Add a commented toc line to archetypes/blog.md, document the switch and the markup.tableOfContents keys in the README, turn it on for the markdown syntax example post and set endLevel to 4 in the example config. Download the current Hugo release, build exampleSite with the command CI uses, confirm the nav in the built post and its absence on the other pages, open the post in a browser in both colour schemes, run npm run beautify and show it changed nothing, and 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 layouts/_default/single.html, layouts/partials/style.html, archetypes/blog.md, README.md, exampleSite/hugo.toml and exampleSite/content/blog/markdown-syntax.md. Its description quotes the hugo build summary, the <nav id="TableOfContents"> element from the built post with its link count, the grep over the other built pages that found no nav, the beautify run with an empty diff, and two screenshots of the post, one per colour scheme. No layout other than the post template changes.

A reviewer checks the position, before the content rather than floating beside it, the endLevel choice for the example site, and whether the switch should default on through [params] for their own blog. After merging, a post that says toc = true gets the table on the next build and every other post stays exactly as it rendered before.

Run it on every Hugo site in the terminal

A developer who has hugo server open and does not want to leave it sends this body from their own machine with the site in resources, and reads the result in the console when the webhook on their API key reports the run. A team that keeps several Hugo sites sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a second send of the same script returns the runs already started rather than a second set of pull requests.

Each run reads its own theme: a site whose single template already calls .TableOfContents gets a pull request that only adds the switch and the styling it lacks, and one that keeps its CSS in assets/ rather than an inline partial gets the rule there.

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

Why run it on Rush?

The method is one template call, but what it renders depends on the whole site: the heading levels authors actually use, the startLevel and endLevel in the config, whether a theme prints the content inside an element the stylesheet targets, and whether posts without headings get an empty box. Those only show in a build, so the agent downloads Hugo in its own sandbox, builds the example site with CI's exact command, reads the generated HTML and opens it in a browser in both colour schemes, and keeps every command and its output in the run's record.

It also keeps the theme's own habits: the inline stylesheet and its variables rather than a new file, the js-beautify formatting the maintainers check by hand, an archetype comment so the switch is discoverable, and a README paragraph. Ten blogs on ten Hugo themes get ten pull requests, each placed where that theme renders a post.

Frequently asked questions

Does this need a Hugo module or a JavaScript library?

No. .TableOfContents is a method on every page object and Hugo builds the list from the rendered headings, so the pull request adds a template condition, a CSS rule and configuration. The theme's promise of no scripts and no stylesheets beyond the inline one still holds.

Why is it off by default?

Because the theme's single template serves every site that uses it, and a two-paragraph post with one heading gains nothing from a one-item list. .Param "toc" reads the page's front matter first and the site's [params] second, so a blog that wants it everywhere sets it once in hugo.toml.

Which headings appear in the table?

Hugo's defaults are startLevel = 2 and endLevel = 3, so ## and ### headings are listed and # and #### are not. The example post in the theme uses #### for its sub-sections, which is why the pull request sets endLevel = 4 in the example config and explains the keys in the README.

Can I move it beside the post instead of above it?

Yes. The nav is a normal element in the main block, so a rule on #TableOfContents with float or a grid on main in style.html places it, and the theme's --width variable of 720px is the constraint to keep in mind. The pull request keeps it above the content so it reads well on a phone, where the theme has no sidebar.

Will the formatter check in CI fail?

CI does not run npm run beautify; it only builds the example site. The agent runs the formatter anyway and shows an empty git diff afterwards, so the template matches what js-beautify would produce and a maintainer who runs it later sees no churn.

More Hugo jobs

The same job on other stacks

Keep reading