# Add Post Series to an Astro Blog from a Linear Issue

Yes. Label the Linear issue and an agent adds series to your Astro content collection, a part navigator on each post, a page per series and docs, then opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-post-series/astro/). 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 Linear issue and reads how posts are modelled before it adds a field. In a blog like satnaing/astro-paper, `src/content.config.ts` defines the `posts` collection with Astro's `glob` loader over `src/content/posts` matching `**/[^_]*.{md,mdx}`, and a zod schema with `title`, `description`, a required `pubDatetime`, optional `modDatetime`, `author` defaulting to the site author, `featured`, `draft`, `tags` defaulting to `others`, `ogImage`, `canonicalURL`, `hideEditPost` and `timezone`. `src/pages/posts/[...slug]/index.astro` builds its paths from `getSortedPosts`, which filters drafts and scheduled posts through `postFilter` and sorts newest first by `modDatetime` or `pubDatetime`, and passes a `prevPost` and `nextPost` to `AdjacentPostNav.astro`, which links to the chronologically adjacent posts under the share links. Tags already have the shape a series needs: `src/utils/getUniqueTags.ts` collects slugs with `slugifyStr`, `src/pages/tags/index.astro` lists them, and `src/pages/tags/[tag]/[...page].astro` paginates each tag's posts with `config.posts.perPage`, which `astro-paper.config.ts` sets to 4. Strings live in `src/i18n/lang/en.ts` with their types in `src/i18n/types.ts`, and `src/content/posts/adding-new-post.mdx` documents every frontmatter property in a table. There is no series concept anywhere in the tree.

The change follows the tag pattern with one difference: order. The schema gains `series: z.string().optional()` and `seriesOrder: z.number().int().positive().optional()`, so `astro check` refuses a post that sets one without the other. `src/utils/getSeries.ts` groups the filtered posts by the slugified series name, sorts each group by `seriesOrder` and then `pubDatetime`, and returns the series with their display names and parts; it reuses `postFilter` so a draft never counts as a part. `src/pages/series/index.astro` lists every series with its part count, and `src/pages/series/[series].astro` renders one series in order with `Card.astro`, under `Breadcrumb`, `Main` and `Footer` the way the tag pages do, without pagination because a series is read in order. `@astrojs/sitemap` picks the new routes up on its own.

On the post page, a new `SeriesNav.astro` under `src/pages/posts/[...slug]/_components` renders above the article for a post that belongs to a series: the series name linked to its page, `Part n of m`, and links to the previous and next part, built with `getPostUrl` so posts in subdirectories keep their URL segments. It carries `data-pagefind-ignore` like `AdjacentPostNav.astro`, so the Pagefind index does not fill with navigation text. `en.ts` and `types.ts` get `seriesTitle`, `seriesDesc` and a `post.seriesPart` string, the frontmatter table in `adding-new-post.mdx` gets rows for the two new properties, and two of the example posts under `src/content/posts/examples` are given a series so the feature is visible in the demo content.

There are no tests in the repository; the types and the build are the check. `pnpm build` runs `astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/`, `pnpm lint` runs ESLint with `eslint-plugin-astro`, and `pnpm format:check` runs Prettier with its Astro and Tailwind plugins. `.github/workflows/ci.yml` runs those three on Node 24 with pnpm 11.3.0 under a three-minute timeout, so the agent does the same in its sandbox, then runs `astro preview` and fetches `/series/`, one series page and one post in the series to read the navigator in the HTML before it opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Add post series: a series name and order in frontmatter, a part navigator on each post in a series, and a page per series.\" Do the work in this repository. Read package.json, astro.config.ts, astro-paper.config.ts, src/content.config.ts, src/pages/posts/[...slug]/index.astro and its _components, src/pages/tags/index.astro, src/pages/tags/[tag]/[...page].astro, src/utils/getUniqueTags.ts, src/utils/getSortedPosts.ts, src/utils/postFilter.ts, src/utils/getPostPaths.ts, src/components/Card.astro, src/i18n/lang/en.ts, src/i18n/types.ts, src/content/posts/adding-new-post.mdx and .github/workflows/ci.yml first. Add optional series and seriesOrder fields to the posts schema, refined so one is not set without the other. Add src/utils/getSeries.ts that groups filtered posts by slugified series and orders parts by seriesOrder then pubDatetime. Add src/pages/series/index.astro and src/pages/series/[series].astro modelled on the tag pages, without pagination. Add a SeriesNav component beside AdjacentPostNav that shows the series link, Part n of m and previous and next part links, marked data-pagefind-ignore, and render it above the article. Add the i18n strings and their types, document the two properties in adding-new-post.mdx, and give two example posts a series. Run pnpm install --frozen-lockfile, pnpm lint, pnpm format:check and pnpm build, then astro preview and fetch the series index, one series page and one post to read the navigator. Do not change astro.config.ts, the Pagefind step or any workflow. Open a pull request that links the issue, lists the files and quotes the check, lint and build 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

What comes back is a pull request on its own branch that changes `src/content.config.ts`, `src/pages/posts/[...slug]/index.astro`, `src/i18n/lang/en.ts`, `src/i18n/types.ts` and `src/content/posts/adding-new-post.mdx`, adds `src/utils/getSeries.ts`, the two pages under `src/pages/series` and `SeriesNav.astro`, and sets the new frontmatter on two example posts. The body links the Linear issue, lists the files, explains the ordering rule and the refinement on the schema, and quotes `astro check`, the lint, the format check and the build summary with the Pagefind index step.

The transcript keeps the install from `pnpm-lock.yaml`, each check with its output including any `astro check` failure before the types were right, the build, and the three fetches from `astro preview` that show the navigator and the series page in rendered HTML. `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the diff per file.

Before merging, a reviewer checks that a draft part is excluded from `Part n of m` the way `postFilter` excludes it elsewhere, that two posts with the same `seriesOrder` sort deterministically, that the series pages render with the `Breadcrumb` and `Main` components rather than a new layout, and that `astro check` is clean with the new optional fields.

## 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 whether series pages should paginate or how the navigator should read, and it fills in no placeholder. Only a change by someone in your Rush org fires it; changes made by an app integration never do, and the automation's `max_runs_per_hour` bounds how many runs a burst of labelling starts.

From your own server, the same run is one `POST /o/{org}/sessions` per issue: put the repository in `resources`, and add the issue's `https://linear.app/<workspace>/issue/<ID>` URL there too so Rush reads it through your Linear connection into the prompt. A `webhook_url` on that key posts `run.completed` or `run.failed` when the turn finishes, with `data.session_url` to read the pull request.

## Why run it on Rush?

A content-collection change is only real once `astro check` has typed the new frontmatter and `astro build` has rendered every post with it, and the Pagefind step after the build is where a navigator without `data-pagefind-ignore` quietly pollutes search. In a Rush sandbox the agent installs from the lockfile with the pnpm version CI uses, runs the three checks end to end and previews the result, so the pull request arrives with rendered HTML rather than a promise.

A label in Linear becomes a reviewable change with the evidence attached: the transcript shows the agent reading the tag pages and `getPostPaths.ts` before writing the series pages, so URLs for posts in subdirectories keep working, and several labelled Astro issues run at once, each in its own sandbox with its own branch.

## Frequently asked questions

### Do existing posts need a change?

No. Both fields are optional in the schema, so every post without them builds as before and shows no navigator. Only a post that sets `series` must also set `seriesOrder`, which the refinement enforces at `astro check` time rather than at runtime.

### Why is the series page not paginated like a tag page?

Because a series is read in order and is rarely longer than a handful of parts, a single ordered list is the clearer page. The tag pages keep their pagination at `config.posts.perPage`. Say in the issue if your series are long and the agent paginates the series page the same way.

### How are parts ordered?

By `seriesOrder` first and `pubDatetime` second, so two parts with the same order number still sort the same way on every build. Drafts and scheduled posts are excluded through `postFilter`, the same rule the home page and the tag pages apply.

### Will the navigator show up in site search?

No. `SeriesNav.astro` carries `data-pagefind-ignore` like the adjacent-post navigation, so Pagefind indexes the article and not the part links. The search page in `src/pages/search.astro` is unchanged.

### Does it work for posts in subdirectories?

Yes. Links in the navigator and on the series page are built with `getPostUrl`, the same helper `Card.astro` uses, which turns a post's directory segments into URL segments, so a part under `src/content/posts/examples` links to `/posts/examples/<slug>` as it does elsewhere.

## More Astro jobs

- [Add PWA Support to an Astro Site](https://getrush.ai/run/add-pwa-support/astro/)
- [Add Reading Time to Posts in an Astro Site from a Linear Issue](https://getrush.ai/run/add-reading-time/astro/)
- [Add Related Posts to an Astro Blog](https://getrush.ai/run/add-related-posts/astro/)

## More jobs like this: Turn a Linear label into a PR

- [Add Priority Classes to Kubernetes Manifests](https://getrush.ai/run/add-priority-classes/kubernetes/)
- [Add Product Reviews to a Medusa Store](https://getrush.ai/run/add-product-reviews/medusa/)
- [Add Prometheus Metrics to an aiohttp App](https://getrush.ai/run/add-prometheus-metrics/aiohttp/)

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