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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.