# Add a Sitemap to a VitePress Site

Yes. An agent turns on VitePress's sitemap with your hostname, sets each post's lastmod from its frontmatter date, adds robots.txt, builds to check, and opens a PR.

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

## What the agent does

The agent reads the site's config and content before it changes anything, because a sitemap is only right if its hostname and dates are. In a blog laid out like vuejs/blog, `.vitepress/config.ts` sets `title`, `description`, `cleanUrls: true`, a `head` with Twitter meta tags, a favicon and an analytics script, and a `buildEnd` hook, `genFeed` from `.vitepress/genFeed.ts`, which loads `posts/*.md` with `createContentLoader`, sorts them by their frontmatter `date` and writes `feed.rss` into the build's `outDir` with the base URL hard-coded as a constant. There is no `sitemap` key. `package.json` runs `vitepress build` and pins `vitepress` on a caret range that `pnpm-lock.yaml` resolves to 1.3.4, with `gray-matter` and `feed` among the dev dependencies and `pnpm` named in `packageManager`. `public/` holds `favicon.ico`, `logo.svg` and two images, and no `robots.txt`. The posts are Markdown files in `posts/`, each with `title`, `date` and `author` in frontmatter, and `vercel.json` only sets `cleanUrls` and a cache header for `/assets/`.

VitePress generates `sitemap.xml` itself once `sitemap.hostname` is set, so the first change is one line in `config.ts`: `sitemap: { hostname: 'https://blog.vuejs.org' }`, the same URL `genFeed.ts` already uses, which the agent lifts into a shared constant so the feed and the sitemap cannot drift. With `cleanUrls` on, the URLs VitePress writes have no `.html`, matching what Vercel serves. The `<lastmod>` entries are the part that takes thought. VitePress fills them from `lastUpdated`, which reads git history at build time, and a blog's meaning of "last modified" is the post's date, not its last typo fix, so the agent uses the `transformItems` hook instead: it reads each post's frontmatter with `gray-matter`, which is already installed, and sets `lastmod` on the matching item from `date`, leaving the index page without one.

Then it adds `public/robots.txt` with `Allow: /` and a `Sitemap:` line pointing at the sitemap's full URL, so crawlers find it without being told, and checks that nothing else in `public/` or `vercel.json` already answers that path.

To verify, the agent runs `pnpm install --frozen-lockfile` and `pnpm build` in its sandbox, which runs `genFeed` and the sitemap writer in the same build, then reads `.vitepress/dist/sitemap.xml` and `.vitepress/dist/robots.txt`. It checks that every file in `posts/` has an entry, that each entry's `lastmod` matches that post's frontmatter `date`, that the index is present, that no URL ends in `.html`, and that `feed.rss` still lists the same posts in the same order, and pastes the sitemap into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a sitemap to this VitePress blog. Read .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/posts.data.ts, package.json, vercel.json, the public directory and the frontmatter of every file in posts first. Set sitemap.hostname in config.ts to the base URL genFeed.ts already uses, moved into one shared constant. Use the transformItems hook to set each post's lastmod from its frontmatter date with gray-matter, which is already a dev dependency, and leave the index without one. Add public/robots.txt with a Sitemap line. Run pnpm install --frozen-lockfile and pnpm build, read .vitepress/dist/sitemap.xml, check that every post is present with the right lastmod, that no URL ends in .html and that feed.rss is unchanged, and open a pull request with the generated sitemap in the description.",
  "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 `.vitepress/config.ts` and `.vitepress/genFeed.ts`, and adds `public/robots.txt`. Its description pastes the generated `sitemap.xml` with one entry per post and the index, shows the `lastmod` of three posts beside their frontmatter dates, and quotes the `pnpm build` output.

The repository has no workflow, so no check runs on the pull request; Vercel builds the branch as it builds any other, and the description names the two paths to open on the preview, `/sitemap.xml` and `/robots.txt`. The run's record keeps the install and the build.

Before merging, a reviewer decides whether the index page should carry a `lastmod` equal to the newest post's date, whether `changefreq` or `priority` are worth setting, and whether `lastUpdated` should be turned on as well for the `<lastmod>` of pages that are not posts.

## Run it on every new site launched

A team that runs several VitePress sites sends this body once per repository to `POST /o/{org}/sessions`, each with its own 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 opening a second pull request. Each run reads its own config: a site with `base` set gets the base appended to `hostname` as VitePress requires, a docs site with no dated content gets `lastUpdated` instead of a frontmatter hook, and a site whose `config.ts` already has `sitemap` gets a comment that nothing is needed.

Afterwards, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds a Markdown file outside posts/, check whether the sitemap's transformItems hook still gives it a sensible lastmod and comment if not" catches the page that the frontmatter rule does not cover. Automation runs are read-only, so the comment is all it posts.

## Why run it on Rush?

A sitemap is a one-line option, and the one line is where it goes wrong: a hostname that differs from the feed's, a `lastmod` that changes every time someone fixes a typo in an old post, a URL with `.html` on a site that serves clean URLs. The agent reads the feed generator and the Vercel config so the sitemap agrees with both, and builds the site in its own sandbox to read the file that would ship.

The build output and the generated `sitemap.xml` stay with the run and are pasted into the pull request, so the review is of the file itself rather than of a config change that looks right. Several sites get the same change at once, each built on its own.

## Frequently asked questions

### Why not just turn on lastUpdated?

Because `lastUpdated` reads the last git commit that touched each file, so fixing a typo in a post from years ago would make it the newest entry in the sitemap. For a blog, the post's frontmatter `date` is the date that means something, and the `transformItems` hook sets `lastmod` from it. The description names `lastUpdated` as the right choice for pages that are not posts.

### Does this change the RSS feed?

Only by moving the base URL into a constant that `genFeed.ts` and the sitemap share, so they cannot disagree. The agent checks that `feed.rss` after the build lists the same posts in the same order as before, and pastes the diff, which should be empty.

### Will the URLs match what Vercel serves?

Yes. `cleanUrls: true` in `config.ts` makes VitePress write URLs without `.html`, and `vercel.json` sets the same option, so the sitemap's `/posts/<slug>` entries are the addresses a visitor sees. The agent checks that no entry ends in `.html` after the build.

### Why add robots.txt?

Because a crawler that has never been told the sitemap's address finds it through the `Sitemap:` line in `robots.txt`, and `public/` has no such file. The agent adds one with `Allow: /` so nothing is blocked by accident.

## More VitePress jobs

- [Add Social Cards to a VitePress Blog](https://getrush.ai/run/add-social-cards/vitepress/)
- [Add Structured Data to a VitePress Blog](https://getrush.ai/run/add-structured-data/vitepress/)
- [Add a Typo Check to a VitePress Site in CI](https://getrush.ai/run/add-typo-check/vitepress/)

## The same job on other stacks

- [Add a Sitemap to an Astro Blog](https://getrush.ai/run/add-sitemap/astro/)
- [Add a Sitemap to a Gatsby Blog](https://getrush.ai/run/add-sitemap/gatsby/)
- [Add a Sitemap to a Jekyll Site](https://getrush.ai/run/add-sitemap/jekyll/)

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