# Add Related Posts to an Astro Blog

Yes. An agent adds a related posts section under each post of your Astro blog, picked by shared tags at build time behind a config flag, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-related-posts/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 modelled before it writes a line. In an Astro blog like `satnaing/astro-paper`, `src/content.config.ts` defines a `posts` collection with the `glob` loader over `src/content/posts`, and its schema has `tags: z.array(z.string()).default(["others"])`, `pubDatetime`, an optional `modDatetime`, `draft`, `featured` and `description`. `src/utils/getSortedPosts.ts` filters through `postFilter`, which drops drafts and, in production, posts scheduled past `config.posts.scheduledPostMargin`, then sorts by `modDatetime ?? pubDatetime` descending. `src/utils/getUniqueTags.ts` slugs each tag with `slugifyStr` and de-duplicates on the slug, so `Astro` and `astro` are one tag. `src/utils/getPostPaths.ts` turns an entry's `id` and `filePath` into its URL with `getPostUrl(id, filePath, locale)`.

The post page is `src/pages/posts/[...slug]/index.astro`. Its `getStaticPaths` already computes `prevPost` and `nextPost` from the sorted list and passes them as props, and the page renders `PostLayout`, `Header`, `BackButton`, `Datetime`, `EditPost`, the article, `ShareLinks`, `AdjacentPostNav` and `Footer`. `_components/AdjacentPostNav.astro` reads its labels from `useTranslations(locale)` as `t.post.previousPost` and `t.post.nextPost`, and marks itself `data-pagefind-ignore` so the search index does not pick up the links. `src/components/Card.astro` is the list item used on the index and tag pages: a link with the title under a `h2` or `h3`, a `Datetime` and the description. Features are switched in `astro-paper.config.ts` and resolved with defaults in `src/config.ts`, whose shape `src/types/config.ts` documents field by field.

The agent adds `src/utils/getRelatedPosts.ts`: for one post it scores every other post that passes `postFilter` by the number of shared tag slugs, computed with the same `slugifyStr` the tag pages use, breaks ties by the newer `modDatetime ?? pubDatetime`, and returns the top few. It computes the list in `getStaticPaths` beside `prevPost` and `nextPost`, so it costs nothing at request time and nothing in the browser. A new `_components/RelatedPosts.astro` renders them as a `data-pagefind-ignore` list of `Card` items with a heading read from a new `t.post.relatedPosts` string added to each file under `src/i18n/lang`. A `features.relatedPosts` flag goes into `src/types/config.ts` with a doc comment, into `src/config.ts` with a default of `true`, and the section renders only when it is on and the list is not empty.

Then it runs what `.github/workflows/ci.yml` runs: `pnpm install --frozen-lockfile` with the pinned pnpm, `pnpm run lint`, `pnpm run format:check`, and `pnpm run build`, which is `astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/`. It opens the built HTML of one post under `dist/` to confirm the section is there with the expected titles and that the `prev` and `next` links are unchanged, and it checks a post whose only tag is the default `others` to see that the section stays empty rather than listing every untagged post.

## 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 related posts to the blog. Under each post, show a few other posts that share its tags, newest first on ties, with a config flag to turn it off.\" Do the work in this repository. Read src/content.config.ts, src/utils/getSortedPosts.ts, src/utils/postFilter.ts, src/utils/getUniqueTags.ts, src/utils/getPostPaths.ts, src/pages/posts/[...slug]/index.astro, its _components/AdjacentPostNav.astro, src/components/Card.astro, src/config.ts, src/types/config.ts, astro-paper.config.ts, the files under src/i18n and .github/workflows/ci.yml first. Add a getRelatedPosts utility that scores posts by shared tag slugs using the existing slugify, excludes the post itself and anything postFilter rejects, and computes the list in getStaticPaths. Render it in a RelatedPosts component that reuses Card, is marked data-pagefind-ignore, and takes its heading from a new i18n string. Add a features.relatedPosts flag with a documented type and a default of true. Run pnpm install --frozen-lockfile, pnpm run lint, pnpm run format:check and pnpm run build, check the built HTML of one tagged post and one post with only the default tag, and open a pull request that explains the scoring and the flag.",
  "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 `src/utils/getRelatedPosts.ts`, `src/pages/posts/[...slug]/_components/RelatedPosts.astro`, a few lines in `src/pages/posts/[...slug]/index.astro`, the new `relatedPosts` string in each language file under `src/i18n/lang`, and the flag in `src/types/config.ts` and `src/config.ts`. The description explains the score, the tie-break and the cap, names the flag, and quotes the `pnpm run build` summary.

The transcript holds the install, the lint and format checks, the `astro check` and `astro build` output, the Pagefind indexing, and the built HTML the agent opened to confirm the section, so a reviewer sees the site built rather than a description of it. The repository's CI workflow runs the same three commands on the pull request.

Before merging, a reviewer checks that the scoring treats `Astro` and `astro` as the same tag, that drafts and scheduled posts never appear in the list, that the section is absent on a post with no shared tags, and that the new i18n key exists in every language file so no locale builds with a missing string. A follow-up message to the same session changes the cap or adds a description line under each title, and the sandbox already has the dependencies installed.

## Run it on every Linear issue labelled agent

In the Project that holds the blog, add an automation with this prompt and a `linear` trigger on `linear.issue.labeled` filtered to the `agent` label. Each labelled theme issue starts its own run in its own sandbox and ends in its own pull request, with the issue's text following the prompt as data; the trigger fills in no placeholder.

Without the automation, a handler on your server does the same: receive Linear's webhook, put the issue text into `input`, and send `POST /o/{org}/sessions` with the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered webhook returns the run already started.

## Why run it on Rush?

Checking a build-time feature in an Astro site means running the whole build, with `astro check`, `astro build` and the Pagefind index, then reading the output HTML. In a Rush sandbox the agent has Node and pnpm, runs that build as often as the change needs, and keeps every run and the HTML it inspected in the record.

A theme feature like this is easy to leave in the backlog because it is small and the build is slow on a laptop mid-edit. Labelling the issue hands it to a sandbox that owns the build, and the pull request arrives with the build output a reviewer would otherwise produce themselves. The same prompt runs on several Astro sites at once, each in its own sandbox.

## Frequently asked questions

### Does this add any JavaScript to the pages?

No. The list is computed in `getStaticPaths` and rendered as plain HTML, the same way the previous and next links already are. The browser receives a list of links and nothing else.

### What counts as related?

The number of tag slugs two posts share, using the `slugifyStr` the tag pages use, so different capitalisation of one tag counts once. Ties go to the newer post by `modDatetime` or `pubDatetime`. Posts with only the default `others` tag match each other on that tag, so the prompt asks the agent to confirm the section is empty for such a post, and a reviewer can decide whether to exclude the default tag.

### Can I turn it off without removing the code?

Yes. The agent adds `features.relatedPosts` to the config type with a documented default of `true`, and the post page renders the section only when it is on. Setting it to `false` in `astro-paper.config.ts` removes the section from every post at the next build.

### Will the search index include the related links?

No. The component carries `data-pagefind-ignore`, as `AdjacentPostNav.astro` does, so Pagefind indexes the article and not the links beneath it.

## More Astro jobs

- [Add a Sitemap to an Astro Blog](https://getrush.ai/run/add-sitemap/astro/)
- [Add a Table of Contents to an Astro Blog](https://getrush.ai/run/add-table-of-contents/astro/)
- [Add View Transitions to an Astro Site](https://getrush.ai/run/add-view-transitions/astro/)

## The same job on other stacks

- [Add Related Posts by Shared Tags to an Eleventy Blog](https://getrush.ai/run/add-related-posts/eleventy/)
- [Add Related Posts to a Gatsby Blog](https://getrush.ai/run/add-related-posts/gatsby/)
- [Add Related Posts to a Hugo Blog](https://getrush.ai/run/add-related-posts/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/)
