# Add a Table of Contents to an Astro Blog

Yes. An agent builds a table of contents from each post's headings in your Astro blog, keeps remark-toc for posts that already opt in, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-table-of-contents/astro/). 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 a component. In a blog shaped like satnaing/astro-paper, `package.json` is `astro-paper-v6` at 6.1.0 on `astro ^7.0.3` with `@astrojs/mdx`, `remark-toc ^9.0.0`, `remark-collapse ^0.1.2`, `rehype-callouts`, Tailwind 4 and Pagefind, requires Node 22.12 or later, and runs `astro check && astro build && pagefind --site dist` for `build`, `eslint .` for `lint` and `prettier --check .` for `format:check`. `astro.config.ts` sets the markdown processor's remark plugins to `remarkToc` and `remarkCollapse` with `test: "Table of contents"`, which means a post only gets a list of its headings if the author writes a `## Table of contents` heading by hand, and several posts under `src/content/posts` do, `adding-new-post.mdx` among them.

`src/pages/posts/[...slug]/index.astro` calls `const { Content } = await render(post)` and ignores the `headings` array `render` also returns, each entry carrying `depth`, `slug` and `text`. The page lays out the `h1`, a `Datetime` row, the `<article id="article">` with `<Content />`, tags, share links and `AdjacentPostNav`, and its inline script already walks `h2` to `h6` and appends `#` links, so every heading has the id the table needs. `src/content.config.ts` defines the `posts` collection with a `glob` loader and a zod schema that has no table-of-contents field, and `src/i18n/lang/en.ts` holds every label under `post`, `nav` and `pages`, typed by `src/i18n/types.ts`.

The agent adds `src/components/TableOfContents.astro` that takes `headings`, keeps depth 2 and 3, nests the third level under its second, and renders a `<nav>` with `aria-labelledby` and links to `#slug`, styled with the theme's Tailwind classes so it reads in both colour schemes. It adds `toc: z.boolean().optional()` to the posts schema so a post can turn the table off, renders the component in `index.astro` between the date row and the article when there are at least two headings, and skips it when `headings` includes one whose `text` is `Table of contents`, so posts that already opt in through remark keep one list rather than two. The label goes into `en.ts` under `post` with its type in `types.ts`, and `eslint.config.js` has `no-console` as an error, so nothing is logged.

The agent runs `pnpm run lint`, `pnpm run format:check` with the repository's prettier plugins for Astro and Tailwind, and `pnpm run build`, which includes `astro check`, then opens a built post from `dist/` in the sandbox browser, clicks three links in the new list and confirms each lands on its heading, with the view transitions router leaving the static list untouched. Those steps are the same ones `.github/workflows/ci.yml` runs on pnpm 11.3.0 and Node 24 with a frozen lockfile.

## 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 posts of this Astro blog and open a pull request. Read package.json, astro.config.ts, src/content.config.ts, src/pages/posts/[...slug]/index.astro, src/layouts/PostLayout.astro, src/i18n/lang/en.ts, src/i18n/types.ts and a few posts under src/content/posts first. Write src/components/TableOfContents.astro that takes the headings array render returns, keeps depth 2 and 3 with the third level nested, and renders a nav with a labelled heading and links to each slug, styled with the theme's Tailwind classes. Add an optional toc boolean to the posts schema that turns it off per post. Render the component in the post page between the date row and the article when the post has at least two headings, and skip it when a heading's text is Table of contents so posts that already use the remark plugin do not get two lists. Add the label to the i18n strings and types. Do not change astro.config.ts or any post. Run pnpm run lint, pnpm run format:check and pnpm run build, open a built post in the browser and check the links land on their headings, and paste the command output in the 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 with one new component, a few lines in `src/pages/posts/[...slug]/index.astro` to pass `headings` and render it, one optional field in `src/content.config.ts`, and one string each in `src/i18n/lang/en.ts` and `src/i18n/types.ts`. The description pastes the lint, format and build output, names which existing posts keep their remark-generated list and which get the new one, and includes a screenshot of a built post with the list beside the first heading.

The repository's `ci.yml` runs the same three commands on the pull request with pnpm 11.3.0 and Node 24, so the check on the pull request repeats what the agent ran.

A reviewer opens two built posts, one that writes `## Table of contents` and one that does not, and confirms each shows exactly one list. They check that a post with `toc: false` shows none, that the links scroll to the right heading with the sticky header in the way, and that the component has no client script. Then they merge.

## Run it on every blog whose posts have no outline

A team that runs several Astro sites from one theme sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own post page and schema, so a site that already renders `headings` somewhere gets the component wired into that spot, and each opens its own pull request.

Give the key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with `session_url` to read the pull request from, and `GET …/sessions/{id}/changes` lists the files the agent changed.

## Why run it on Rush?

The difference between a table of contents that works and one that does not is a handful of details: heading ids that match the slugs, one list per post rather than two, no duplicate with the remark plugin, and a build that still passes `astro check`. In a Rush sandbox the agent builds the site, opens the result in a browser and clicks the links, and the output and screenshot stay in the run's record beside the pull request.

On a laptop this is an hour of reading how `render` exposes headings and how the theme styles a nav, then checking posts one by one. The agent does it in one pass, and the same request works unchanged on the next site built from the theme.

## Frequently asked questions

### What about posts that already write a Table of contents heading?

They keep the list `remark-toc` generates and `remark-collapse` folds, because the component checks `headings` for an entry whose text is `Table of contents` and renders nothing in that case. Nothing in `astro.config.ts` changes.

### Can a post turn it off?

Yes. The posts schema gains `toc: z.boolean().optional()`, and `toc: false` in a post's frontmatter skips the component. Posts with fewer than two headings skip it on their own.

### Does it add any client JavaScript?

No. The list is rendered at build time from `headings`, and the existing inline script that adds `#` links to headings already gives every heading an id. The view transitions router swaps the static markup like the rest of the page.

### Will the heading ids match?

Yes. Astro assigns the ids when it renders markdown and reports the same values as `slug` in `headings`, so the links point at ids that exist in the article. The agent clicks them in the built site to confirm.

## More Astro jobs

- [Add View Transitions to an Astro Site](https://getrush.ai/run/add-view-transitions/astro/)
- [Fix a Failing CI Build for an Astro Site](https://getrush.ai/run/fix-failing-ci/astro/)
- [Turn Sentry Errors Into Fix Pull Requests for an Astro Site](https://getrush.ai/run/fix-sentry-errors/astro/)

## The same job on other stacks

- [Add a Table of Contents to Eleventy Blog Posts](https://getrush.ai/run/add-table-of-contents/eleventy/)
- [Add a Table of Contents to Gatsby Blog Posts from a Linear Issue](https://getrush.ai/run/add-table-of-contents/gatsby/)
- [Add a Table of Contents to a Hugo Blog](https://getrush.ai/run/add-table-of-contents/hugo/)

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