# 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 Rush](https://cloud.getrush.ai/run/add-table-of-contents/hugo/). Opens 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`

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

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

- [Add a Typo Check to a Hugo Site](https://getrush.ai/run/add-typo-check/hugo/)
- [Add a Version Menu to a Hugo Docsy Site](https://getrush.ai/run/add-versioned-docs/hugo/)
- [Review Pull Requests on a Hugo Theme](https://getrush.ai/run/review-pull-requests/hugo/)

## The same job on other stacks

- [Add a Table of Contents to Jekyll Posts](https://getrush.ai/run/add-table-of-contents/jekyll/)
- [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/)

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