# Add a Table of Contents to Gatsby Blog Posts from a Linear Issue

Yes. An agent reads the Linear issue, adds a table of contents to each Gatsby blog post from its Markdown headings, builds the site and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-table-of-contents/gatsby/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the issue and the repository in its own cloud sandbox and reads how posts are built before it changes anything. In a site like gatsbyjs/gatsby-starter-blog (Gatsby `^5.14.6`, React 18, npm with a `package-lock.json`), `gatsby-config.js` sources Markdown from `content/blog` through `gatsby-source-filesystem` and `gatsby-transformer-remark`, with `gatsby-remark-images`, `gatsby-remark-responsive-iframe` and `gatsby-remark-prismjs` as the remark plugins. `gatsby-node.js` creates one page per post with `src/templates/blog-post.js`, passing `id`, `previousPostId` and `nextPostId` in context, and its `createSchemaCustomization` declares `Frontmatter` as `title`, `description` and `date` so queries stay valid when a field is missing. The template's `BlogPostBySlug` query fetches `html`, `excerpt(pruneLength: 160)` and the frontmatter, and renders the body with `dangerouslySetInnerHTML` inside an `<article>`.

Then it checks what the content gives it to work with. `content/blog/hello-world/index.md` and `content/blog/new-beginnings/index.md` use `##` and `###` headings; `content/blog/my-second-post/index.md` has none. `gatsby-transformer-remark` already exposes a `tableOfContents` field on every `MarkdownRemark` node, built from those headings, but its links point at heading anchors that nothing in this config creates. So the plan has two parts: give headings ids, and render the field.

The change lands in three files. In `gatsby-config.js` the agent adds `gatsby-remark-autolink-headers` to the `gatsby-transformer-remark` plugin list ahead of `gatsby-remark-prismjs`, the order that plugin's own documentation asks for, so every heading gets an id and an anchor link. In `src/templates/blog-post.js` the query gains `tableOfContents(maxDepth: 3)` and the component renders it in a `<nav aria-label="Table of contents">` between the header and the body, only when the string is non-empty, so a post like my-second-post shows nothing extra. `createSchemaCustomization` in `gatsby-node.js` gains an optional `toc: Boolean` frontmatter field, so an author can switch the list off per post without the query failing on posts that never set it, and `src/style.css` gets a few lines so the list sits with the existing `.blog-post` styles.

The repository's `test` script only prints a reminder to write tests and exits non-zero, so the proof is the build. The agent runs `npm ci`, then `npm run build`, serves the output with `npm run serve`, and reads the HTML of `/hello-world/` and `/my-second-post/` to confirm the first has a navigation list whose hrefs match heading ids on the same page and the second has no list. It runs `npm run format` so Prettier `^2.8.8` leaves the diff clean, and pushes once the build is green.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A Linear issue labeled agent says: \"Add a table of contents at the top of each blog post, generated from the post's headings, with links that jump to each section. Skip posts with no headings. Let a post opt out with toc: false in its frontmatter.\" Before changing anything, read gatsby-config.js, gatsby-node.js and src/templates/blog-post.js to see how Markdown posts are transformed and rendered and which remark plugins are configured. Use the tableOfContents field gatsby-transformer-remark provides, add the remark plugin that gives headings ids and anchors in the position its documentation requires relative to the prism plugin, render the list in a labelled nav only when it is non-empty, and declare the optional toc frontmatter field in the schema customization so queries stay valid. Keep the existing post layout, previous and next links and SEO head. Run the production build, serve it and check the generated HTML of a post with headings and a post without, then open a pull request that links back to the issue and describes what was already available and what was added.",
  "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 on its own branch with a diff over `gatsby-config.js`, `gatsby-node.js`, `src/templates/blog-post.js`, `src/style.css`, `package.json` and `package-lock.json`. Its description says what the agent found, that the `tableOfContents` field already existed but nothing gave headings ids, and names the plugin it added and where in the remark plugin order it sits.

The transcript is the proof: the `npm ci` and `npm run build` output, the served pages, and the HTML the agent read back showing the `<nav>` with anchor links on a post with headings and no `<nav>` on one without. If the repository runs a build on pull requests, that check runs there too.

Before merging, a reviewer checks that the anchor ids match the links on long posts with duplicate heading text, that `maxDepth` matches what the issue wants, that a post with `toc: false` renders no list, and that the new nav reads correctly with a screen reader and does not shift the existing header layout.

## Run it on every Linear issue labelled agent

In the console, an automation with a `linear` trigger on `linear.issue.labeled` and the label `agent` starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so each issue carries its own wording, such as the heading depth or the opt-out field name. Changes made by an app integration never fire it, and the automation's `max_runs_per_hour` bounds how many runs a burst of labelling can start.

From your own server, the same job is one `POST /o/{org}/sessions` per issue, with the repository in `resources` and the issue's `https://linear.app/<workspace>/issue/<ID>` URL beside it so Rush reads the issue through your Linear connection. A `webhook_url` on the API key receives `run.completed` or `run.failed` for every run that key starts, with the `session_url` to read the pull request link from.

## Why run it on Rush?

A Gatsby change is only real once `gatsby build` has run the GraphQL queries and written the HTML, and a remark plugin in the wrong order fails quietly rather than loudly. In a Rush sandbox the agent runs the full production build, serves it and reads the generated pages back, so the pull request arrives with a green build and the exact HTML it produced, instead of a config change that looked right in the editor.

A label in Linear becomes a reviewable pull request whose reasoning is on the record. The transcript shows the agent reading the existing config and template before it edits them and every build with its output, and several labelled issues can run at once, each in its own sandbox on its own branch, each linking back to the issue it answers.

## Frequently asked questions

### Does it work with MDX posts too?

The starter uses `gatsby-transformer-remark` and plain Markdown, which is what this page describes. A site on `gatsby-plugin-mdx` exposes a similar `tableOfContents` field with a different shape, and the agent reads the config first and adapts; the pull request says which path it took.

### What if two headings have the same text?

The autolink plugin gives each heading a unique id by appending a suffix to repeats, and the `tableOfContents` field uses those same ids, so the links stay distinct. The reviewer can confirm on a post with repeated section titles.

### Can I hide the list on short posts?

Posts with no headings render no list at all, and any post can set `toc: false` in its frontmatter. The field is declared in `createSchemaCustomization`, so posts that never set it do not break the query.

### There are no tests in this repository. What is the check?

The production build and the pages it produces. The agent runs `npm run build`, serves the result and reads the HTML of a post with headings and one without, and those outputs are in the transcript for the reviewer to see.

## More Gatsby jobs

- [Add Tag Pages to a Gatsby Blog from a Linear Issue](https://getrush.ai/run/add-tag-pages/gatsby/)
- [Convert a Gatsby Site From JavaScript to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/gatsby/)
- [Migrate a Gatsby Blog from Markdown to MDX](https://getrush.ai/run/migrate-to-mdx/gatsby/)

## The same job on other stacks

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

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