# Add Structured Data to a VitePress Blog

Yes. An agent adds JSON-LD BlogPosting markup to every post of your VitePress blog from its front matter through a build hook, checks the output, and opens a PR.

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

## What the agent does

The agent reads what each post already knows about itself before it writes markup for search engines. In a blog laid out like vuejs/blog, every file in `posts/` carries `title`, `date`, `author`, `twitter` and either a `gravatar` hash or an `avatar` URL in its front matter, and the fifteen posts have no `description` field. `.vitepress/theme/posts.data.ts` turns that into a list with `createContentLoader('posts/*.md', { excerpt: true })`, and `Article.vue` renders the title, a `<time datetime>` from `Date.vue` and the author block from `Author.vue`, which links `twitter` to `https://twitter.com/<handle>`. `.vitepress/config.ts` sets the site `title` and `description`, `cleanUrls: true`, three `twitter:` metas and a favicon in `head`, and runs `genFeed` from `genFeed.ts` at `buildEnd`, which hardcodes `https://blog.vuejs.org` as the base URL. There is no JSON-LD anywhere in the theme, `package.json` builds with `vitepress build` on VitePress 1.3 and `pnpm@9.8.0`, `gray-matter` is already a dev dependency, and `tsconfig.json` is `strict` with `NodeNext` modules over `.vitepress/**`.

The change is a `transformPageData` hook in `config.ts`, kept in its own file `.vitepress/structuredData.ts`. For a page whose `relativePath` starts with `posts/`, it builds a `BlogPosting` object: `headline` from `frontmatter.title`, `datePublished` as the ISO form of `frontmatter.date` set to UTC noon the way `posts.data.ts` does, `author` as a `Person` with `name` from `frontmatter.author` and `url` from the Twitter handle when there is one, `image` from `avatar` or the Gravatar URL `Author.vue` builds, `mainEntityOfPage` as the base URL plus the path with `.md` removed, and `publisher` as an `Organization` named Vue.js with the logo already used in `twitter:image`. The `description` comes from the first paragraph of the file, read with `gray-matter` from `siteConfig.srcDir`, because the front matter has none. The hook pushes `['script', { type: 'application/ld+json' }, json]` onto `pageData.frontmatter.head`, with `<` escaped as `\u003c` in the JSON string so a post body can never close the script tag.

The home page gets a `Blog` object the same way, listing each post's `url` and `headline` from the same loader data, so the index and the posts agree. The base URL moves to a `.vitepress/site.ts` constant that `genFeed.ts` and the new hook both import, so the feed and the markup cannot drift. VitePress keys `meta` tags for de-duplication but never de-duplicates `script` tags, so the hook runs once per page and checks `frontmatter.head` for an existing JSON-LD script before pushing, which also makes a post that sets its own markup win. Because `transformPageData` runs in dev as well as at build, the file read is cheap and cached by path.

To check it, the agent runs `pnpm install --frozen-lockfile` and `pnpm build` in its sandbox, extracts the JSON-LD script from `.vitepress/dist/posts/vue-3-5.html` and from `index.html`, parses each with `node`, and compares `headline`, `datePublished` and `author.name` to the front matter of `posts/vue-3-5.md`. It adds `scripts/check-structured-data.mjs`, wired as `pnpm check:jsonld`, which does that for every post in `dist` and fails when a page has none or two, so the check can run after any later build. Since Vercel builds the site from `vercel.json` with the same `build` script, nothing changes in hosting.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add JSON-LD structured data to this VitePress blog. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/posts.data.ts, Article.vue, Author.vue, Date.vue, Home.vue, Layout.vue, index.md, tsconfig.json and the front matter of every file in posts first. Add a transformPageData hook in .vitepress/structuredData.ts that pushes a BlogPosting script onto frontmatter.head for each post, with headline, datePublished at UTC noon like posts.data.ts, author as a Person with the Twitter URL when present, image from avatar or the Gravatar URL, mainEntityOfPage from the site base URL and the path without .md, publisher as an Organization with the logo from twitter:image, and description from the first paragraph read with gray-matter; escape < in the JSON. Give the home page a Blog object listing the posts. Move the base URL to a shared constant that genFeed.ts also imports. Add scripts/check-structured-data.mjs as pnpm check:jsonld that parses the JSON-LD of every built post and fails on a missing or duplicate script. Run pnpm install --frozen-lockfile, pnpm build and pnpm check:jsonld and quote the output. Open a pull request.",
  "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 adds `.vitepress/structuredData.ts`, `.vitepress/site.ts` and `scripts/check-structured-data.mjs`, and changes `.vitepress/config.ts` (the hook), `.vitepress/genFeed.ts` (the imported base URL) and `package.json` (the `check:jsonld` script). Its description quotes the `pnpm build` and `pnpm check:jsonld` output and pastes the parsed `BlogPosting` for one post beside that post's front matter.

A reviewer builds the site, opens a post's HTML and reads the script, then pastes it into a schema validator to see the `BlogPosting` and its `Person` resolve with no missing required field. In the code they check that the description comes from the post body and not from the site description, and that the `date` handling matches `posts.data.ts` so the markup and the visible date never disagree.

The theme components and the posts are unchanged. The markup is in `<head>` only, and the RSS feed carries the same base URL it did, now from the shared constant.

## Run it on every new post

Once the hook is in, every post gets its markup at build time with no further run. For the rest of a team's sites, a handler on its own server sends this body to `POST /o/{org}/sessions` once per repository that builds with `vitepress build` and has no `application/ld+json` in its config, 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.

A Rush automation with a `github` trigger on `pull_request.opened` can comment when a new file under `posts/` lacks a front matter field the hook reads, such as `author` or `date`; its runs are read-only, so they comment and never push.

## Why run it on Rush?

Structured data is judged by the built HTML, not by the hook that produces it. The agent builds the site in its own sandbox, extracts the script from the output and parses it against the post it came from, and keeps the build log and the check output with the pull request, so the reviewer sees the markup a crawler would see.

A team with several documentation or blog sites on VitePress starts the same request for each at once. Each run reads its own theme and front matter, so a site with a `description` field uses it and one without reads the first paragraph, and each pull request says which.

## Frequently asked questions

### Why transformPageData and not transformHead?

`transformHead` runs only at build and its tags are not updated on client-side navigation, while `transformPageData` runs in dev too and its `frontmatter.head` entries follow the page. Both would produce the same HTML in `dist`; the hook chosen also lets a post override the markup from its own front matter.

### Where does the description come from?

The posts have no `description` field, so the hook reads each file with `gray-matter`, already a dev dependency, and takes the first paragraph after the front matter. Adding a `description` to a post's front matter makes the hook use it instead, which the pull request documents.

### Will it break the RSS feed?

No. `genFeed.ts` keeps producing `feed.rss` at `buildEnd`; the only change there is importing the base URL from `.vitepress/site.ts` instead of a string literal, so the feed and the markup use one origin.

### Does the script tag get duplicated?

VitePress does not de-duplicate `script` entries in `head`, so the hook checks `frontmatter.head` for an existing `application/ld+json` entry before pushing, and `pnpm check:jsonld` fails a build where a post ends up with none or two.

## More VitePress jobs

- [Add a Typo Check to a VitePress Site in CI](https://getrush.ai/run/add-typo-check/vitepress/)
- [Add Versioned Docs to a VitePress Site](https://getrush.ai/run/add-versioned-docs/vitepress/)
- [Add Author Pages to a VitePress Blog](https://getrush.ai/run/add-author-pages/vitepress/)

## The same job on other stacks

- [Add Schema.org Structured Data to a Wagtail Site](https://getrush.ai/run/add-structured-data/wagtail/)
- [Add JSON-LD Structured Data to a Zola Site](https://getrush.ai/run/add-structured-data/zola/)
- [Add JSON-LD Structured Data to an Eleventy Blog](https://getrush.ai/run/add-structured-data/eleventy/)

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