# Add an RSS Feed to a Starlight Docs Site

Yes. An agent adds an rss.xml endpoint to your Starlight site built from the docs collection, dated from Git, linked from every page, built and checked, as a PR.

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

## What the agent does

The agent reads how the site is built before adding a feed, because the feed has to come from the same collection and the same URLs as the pages. In a site started from Starlight's `examples/basics`, `package.json` depends on `@astrojs/starlight` ^0.42.7, `astro` ^7.2.10 and `sharp`, with `dev`, `build` and `preview` scripts. `astro.config.mjs` registers the `starlight` integration with the title `My Docs`, one GitHub social link and a sidebar of a `Guides` group pointing at `guides/example` and a `Reference` group autogenerated from the `reference` directory; it sets no `site`. `src/content.config.ts` defines one collection, `docs`, with `docsLoader()` and `docsSchema()`, whose frontmatter is a required `title`, an optional `description`, an optional `lastUpdated` that is a date or a boolean, and `draft`, which defaults to false. The content is `index.mdx`, a splash page, plus `guides/example.md` and `reference/example.md`. No `src/pages` directory exists, and nothing in the repository mentions a feed.

The feed is an Astro endpoint, which Starlight allows beside its own routes through the `src/pages/` directory. The agent installs `@astrojs/rss` and writes `src/pages/rss.xml.ts`, whose `GET` calls `getCollection('docs')`, drops the entry whose id is `index` because the splash page is not an article, drops any entry with `draft` set, and maps the rest to items with `title` from `data.title`, `description` from `data.description` when there is one, and `link` built from the entry's `id` with a trailing slash, which is the path Starlight serves the page at. `@astrojs/rss` needs `site`, so the agent adds `site` to `defineConfig` with a placeholder address the pull request tells the reader to replace, and `rss()` takes it from `context.site` so there is one place to change.

A feed without dates is a list, not a feed, and the schema makes `lastUpdated` optional, so the agent dates each item the way Starlight dates its own footer: from Git. For an entry whose `lastUpdated` is a date, that is `pubDate`; for the rest, the endpoint runs `git log -1 --format=%cI` on the entry's `filePath` with `execFileSync` and parses the result, falling back to the build time when the repository has no history for the file, which is what happens on a platform that builds from a shallow clone, and the pull request names that case. Items are sorted newest first. The endpoint also sets `customData` with a `<language>` element taken from the site's locale.

Readers find a feed through the page head, so the agent adds a `head` entry to the Starlight config: a `link` tag with `rel="alternate"`, `type="application/rss+xml"`, the site title and `href="/rss.xml"`, which Starlight writes into every page as is. In the sandbox it runs `npm install` and `npm run build`, checks that `dist/rss.xml` exists and parses as XML with one item per non-splash page, each `link` beginning with the configured `site`, runs `npm run preview` and fetches `/rss.xml` and `/guides/example/` to confirm the item links resolve to real pages and the head carries the alternate link, and opens the pull request with the generated feed pasted in.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add an RSS feed to this Starlight site. Read package.json, astro.config.mjs, src/content.config.ts, tsconfig.json and every file under src/content/docs first. Install @astrojs/rss and write src/pages/rss.xml.ts whose GET reads the docs collection with getCollection, skips the entry with id index and any entry with draft set, and maps the rest to items with the page title, its description when present, and a link made from the entry id with a trailing slash. Use the entry's lastUpdated frontmatter as pubDate when it is a date; otherwise read the file's last commit date from Git with git log -1 --format=%cI on its filePath, and fall back to the build time when Git has no history, saying so in the pull request. Sort items newest first and set a language element in customData. Add site to defineConfig in astro.config.mjs with a placeholder the README tells the reader to replace, and add a head entry to the starlight config with a link tag rel alternate, type application/rss+xml, the site title and href /rss.xml. Run npm install and npm run build, confirm dist/rss.xml parses as XML with one item per non-splash page and links that start with site, run npm run preview and fetch /rss.xml and one page to confirm the links resolve and the head has the alternate link, then open a pull request that pastes the feed.",
  "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 that adds `src/pages/rss.xml.ts`, changes `astro.config.mjs` for `site` and the `head` entry, adds `@astrojs/rss` to `package.json` and the lockfile, and adds a note to `README.md` on replacing the placeholder site address. The description pastes the generated `rss.xml` from the build, with one `<item>` per page under `guides` and `reference`, each dated from Git and linked under the configured site, and the `<link rel="alternate">` line as it appears in a built page's head.

The run's record holds `npm install`, the full `astro build` output, the XML parse of the feed, and the preview requests to the feed and a page. The Markdown and MDX content is untouched, and no page's frontmatter changes; pages that want a fixed date can set `lastUpdated` and the endpoint prefers it.

Before merging, a reviewer sets the real `site`, decides whether the feed should list every page or only a `guides` subtree, which is a one-line filter on the entry id, and whether `lastUpdated: true` should also be turned on in the Starlight config so the footer and the feed agree on dates.

## Run it on every new docs site

A team with several Starlight sites starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads that site's own collection and locales, so a site with `i18n` configured gets one feed per locale root and a site with a `site` already set keeps it.

Afterwards, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "build the site and compare dist/rss.xml with the one on main; comment with the items added, removed or redated" shows reviewers what subscribers will see before a docs change merges. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

A feed endpoint is a few lines, and the ways it goes wrong are only visible after a build: a missing `site` makes `rss()` throw, a splash page shows up as an article, item links point at `/index/`, and every item carries the same date because nothing set one. The agent builds the site in its own sandbox, parses the feed it produced, requests the pages the items link to, and reads the head of a built page, so each of those is checked before review.

The sandbox keeps the build output and the generated feed with the run, and the pull request pastes them. For a team with many Starlight sites, each gets its own run and its own pull request, with links and dates taken from that site's content and Git history rather than copied from another.

## Frequently asked questions

### Why does the feed need site in astro.config.mjs?

Because feed items must carry absolute links, and `@astrojs/rss` builds them from `context.site`, which is only set when `defineConfig` has `site`. The example config has none, so the agent adds a placeholder and says in the README and the pull request to replace it. The build check confirms every item link starts with that value.

### Where do the dates come from?

From the page's `lastUpdated` frontmatter when it is a date, and otherwise from the last commit that touched the file, read with `git log` on the entry's `filePath` at build time, which is how Starlight dates its own footer. On a shallow clone with no history the endpoint falls back to the build time; the pull request says so and names the fix of a full clone or explicit frontmatter dates.

### Will the splash page or drafts appear in the feed?

No. The entry with id `index` is skipped because it is the landing page, and entries with `draft` set are skipped, matching what Starlight leaves out of a production build. A reviewer who wants only one directory in the feed changes the filter on the entry id.

### Does this change how Starlight renders pages?

No. The endpoint lives in `src/pages`, which Starlight leaves alone, and the only change to the rendered pages is one `link` tag in the head from the `head` config entry, which Starlight writes into every page unchanged. The content collection, sidebar and components are as they were.

## More Starlight jobs

- [Add a Typo Check to Starlight Docs](https://getrush.ai/run/add-typo-check/starlight/)
- [Add Versioned Docs to a Starlight Site](https://getrush.ai/run/add-versioned-docs/starlight/)
- [Run an SEO Audit on a Starlight Site](https://getrush.ai/run/seo-audit/starlight/)

## The same job on other stacks

- [Add an RSS Feed to a SvelteKit App](https://getrush.ai/run/add-rss-feed/sveltekit/)
- [Add an RSS Feed to a Wagtail Blog](https://getrush.ai/run/add-rss-feed/wagtail/)
- [Add an RSS Feed to a Contentlayer Blog](https://getrush.ai/run/add-rss-feed/contentlayer/)

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