All jobs

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

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

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading