All jobs

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

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

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

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

The same job on other stacks

Keep reading