All jobs

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

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading