# Add a Blog to a Starlight Docs Site

Yes. An agent installs the starlight-blog plugin, extends the content schema, adds the first post with an author, builds the site to check the routes and opens a PR.

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

## What the agent does

Starlight has no blog of its own, so the agent reads the site's configuration to see what the plugin has to fit into. In a site laid out like the `examples/basics` project in withastro/starlight, `package.json` depends on `@astrojs/starlight` `^0.42.7`, `astro` `^7.2.10` and `sharp` `^0.35.3`, with `dev`, `build` and `preview` scripts and nothing else. `astro.config.mjs` calls `starlight()` with a `title` of `My Docs`, one `social` link to GitHub, and a `sidebar` of two groups: `Guides` with the explicit entry `guides/example`, and `Reference` autogenerated from the `reference` directory. There is no `site` option, no `plugins` array and no `src/pages`. `src/content.config.ts` defines one collection, `docs`, with `docsLoader()` and `docsSchema()`. The content is three files, `index.mdx`, `guides/example.md` and `reference/example.md`, plus `src/assets/houston.webp` and `public/favicon.svg`.

The plugin is `starlight-blog`, whose current release requires `@astrojs/starlight` at or above `0.42.0`, which this site meets. The agent installs it with the package manager the lockfile names, then makes the two configuration changes the plugin's own getting-started guide asks for: `plugins: [starlightBlog({...})]` inside the `starlight()` call, and in `src/content.config.ts` the schema becomes `docsSchema({ extend: (context) => blogSchema(context) })` with `blogSchema` imported from `starlight-blog/schema`, so a post's frontmatter can carry `date`, `authors`, `tags`, `cover` and the other blog fields. In the plugin options it sets `title`, keeps `prefix` at the default `blog` so the index is at `/blog/` and posts under `/blog/<slug>`, keeps `navigation` at `header-end` so a Blog link appears before the theme switcher, and defines one global author under `authors` with `name`, `title` and a `picture` under `public/`, so posts that name no author fall back to it. It turns on `metrics.readingTime` and leaves `postCount` at its default of five per page.

The first post goes in `src/content/docs/blog/hello-blog.md` with `title`, `date` and a short body, because the plugin reads posts from `src/content/docs/blog/`, a folder that does not exist yet. The agent does not set Astro's `site` option on its own: with it unset, the plugin's RSS feed and structured data stay off, and setting it is the reader's decision because it names their public URL. The pull request shows the one-line `site` change and explains that once it is set the plugin adds `/blog/rss.xml`, an RSS link in the blog sidebar and a feed icon in the header on its own, so a site that already followed a separate RSS guide should check it does not end up with two feeds.

To check it, the agent runs `npm run build` in its sandbox and reads the output under `dist/`: `dist/blog/index.html` for the post list, `dist/blog/hello-blog/index.html` for the post, and the absence of `dist/blog/rss.xml` while `site` is unset. It then runs `npm run preview` and fetches `/`, `/blog/` and the post with `curl`, checking that the header carries the Blog link and the post page carries the author block and the reading time. It also runs `npx astro check` when `@astrojs/check` is present and otherwise says so. The docs pages, the sidebar groups and the existing three content files are not changed.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a blog to this Starlight site with the starlight-blog plugin. Read package.json and the lockfile, astro.config.mjs, src/content.config.ts, tsconfig.json and every file under src/content/docs first. Install starlight-blog with the package manager the lockfile names. Register it in the starlight plugins array with a title, the default blog prefix, header-end navigation, one global author with a picture under public, and reading time on. Extend the docs schema with blogSchema from starlight-blog/schema. Add a first post under src/content/docs/blog with title and date. Do not set the Astro site option; explain in the pull request that it turns on the plugin's RSS feed and structured data and show the one-line change. Run the build, list the blog files under dist, run preview and curl the index, the blog list and the post, and open a pull request with that 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

The pull request changes `package.json` and the lockfile, `astro.config.mjs` and `src/content.config.ts`, and adds `src/content/docs/blog/hello-blog.md` and the author picture under `public/`. Its description pastes the `astro build` summary, the list of files under `dist/blog/`, and the `curl` checks against `astro preview` showing the Blog link in the header and the post with its author and reading time.

The run's record keeps the plugin's installed version, the build output and each `curl`, so a reviewer can see the exact routes the site gained without running it. If the repository has a deploy workflow, it builds the same tree on the pull request's branch.

Before merging, a reviewer writes the real first post, picks the author details, decides whether to set `site` now to get the feed, and whether the blog should sit at `/blog/` or under another `prefix` such as `news`. The docs content and sidebar are untouched.

## Run it on every Starlight site that needs a blog

A company with several product docs sites starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with the 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. Each run reads its own `astro.config.mjs`, so a site that already extends `docsSchema` gets `blogSchema` merged with the existing extension instead of replacing it, and a site with `site` already set gets the RSS feed noted as switched on.

After that, a Linear issue labelled `blog-post` in the Project can start a run through an automation with a `linear` trigger and the prompt "write the post this issue describes under src/content/docs/blog with today's date and the author it names, build the site and open a pull request"; the trigger adds the issue after the prompt. The run reads the issue through the Linear connection and the post lands as a pull request for an editor to review.

## Why run it on Rush?

Adding a plugin sounds like one line, but a Starlight site has three places that must agree: the plugin options, the content schema and the folder the posts live in. Miss the schema change and every post with an `authors` field fails the build; set `site` without noticing and a second RSS feed appears beside one the team already wired. The agent reads the real config, builds the site in its sandbox and reads the generated files before it opens the pull request.

Every command stays with the run, from the install to each `curl`, and the pull request quotes them. A team with five docs sites gets five pull requests at once, each built and checked on its own machine.

## Frequently asked questions

### Does this change my existing docs pages or sidebar?

No. The `sidebar` groups in `astro.config.mjs` and the three content files stay as they are. The plugin adds a Blog link in the header and its own sidebar on blog pages; `navigation` can be set to `none` if the team wants to place the link elsewhere.

### Why not set the site option?

Because `site` is the public URL of the deployed docs, which the reader knows and the agent does not, and because setting it switches on the plugin's RSS feed and structured data. The pull request shows the change and what it enables, so the reviewer makes that call once with the real URL.

### What does a post need in its frontmatter?

`title` and `date` at minimum. `authors` can be a name with `title`, `picture` and `url`, or the key of a global author from the plugin configuration; `tags` and `cover` are optional. Posts live under `src/content/docs/blog/` and the schema extension makes the fields type-checked at build time.

### Can the blog have more than one instance, for a changelog and a blog?

Yes. The plugin accepts an array of configurations, each with its own unique `prefix` and posts folder, and each RSS-enabled instance gets its own feed. The agent sets up one instance; the pull request names the option for a second.

## More Starlight jobs

- [Add a GitHub Pages Deploy Workflow to a Starlight Docs Site](https://getrush.ai/run/add-deploy-workflow/starlight/)
- [Add Giscus Comments to a Starlight Site](https://getrush.ai/run/add-giscus-comments/starlight/)
- [Add i18n to a Starlight Docs Site](https://getrush.ai/run/add-i18n/starlight/)

## More jobs like this: Hand off a long task

- [Add a Buildifier Check to CI for a Bazel Repository](https://getrush.ai/run/add-buildifier-to-ci/bazel/)
- [Add a Bundle Size Budget to a Vite App](https://getrush.ai/run/add-bundle-size-budget/vite/)
- [Add a Bundle Size Check to a Lit Component](https://getrush.ai/run/add-bundle-size-check/lit/)

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