# Add Structured Data to a Gatsby Blog

Yes. An agent adds BlogPosting and WebSite JSON-LD to your Gatsby blog from siteMetadata and post frontmatter, checks it in the built HTML, and opens a PR.

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

## What the agent does

The agent reads where the page metadata already comes from, because structured data that disagrees with the visible page is worse than none. In a blog shaped like gatsbyjs/gatsby-starter-blog, `package.json` pins `gatsby ^5.14.6`, `react ^18.1.0`, `gatsby-plugin-feed`, `gatsby-plugin-manifest` and `gatsby-transformer-remark`, with `npm` as the package manager from `package-lock.json` and no `test` script. `gatsby-config.js` holds `siteMetadata` with `title`, `author.name`, `author.summary`, `description`, `siteUrl` and `social.twitter`. `src/components/seo.js` is a `Seo` component that reads that metadata with `useStaticQuery` and renders `<title>`, `description`, Open Graph and Twitter tags, and is used from each page's exported `Head`. `src/templates/blog-post.js` already marks the article with `itemScope` and `itemType="http://schema.org/Article"` microdata and queries `title`, `date`, `description` and `excerpt` for each post, and `gatsby-node.js` creates one page per Markdown file with a `slug` field.

The agent adds JSON-LD rather than extending the microdata, because the Gatsby `Head` API renders a `<script type="application/ld+json">` cleanly and search engines read it without a DOM parse. `seo.js` gains an optional `schema` prop that, when present, renders the script with `JSON.stringify`. `blog-post.js`'s `Head` builds a `BlogPosting` object from the page query: `headline` from `title`, `datePublished` from a new raw `date` field in the query beside the formatted one, `description`, `author` as a `Person` with `author.name` from `siteMetadata`, `url` and `mainEntityOfPage` from `siteUrl` plus the `slug` already in `fields`, and `publisher` from the site title. `src/pages/index.js`'s `Head` gets a `WebSite` object with `name`, `url` and `description`.

Because `gatsby-node.js` declares `Frontmatter.date` as `Date @dateformat` in `createSchemaCustomization`, the raw ISO date is one more field in the template query, `rawDate: date`, so the formatted string the page shows stays as it is. The `siteUrl` in `siteMetadata` ends with a slash and `slug` starts with one, so the agent joins them without a double slash, the same join `gatsby-plugin-feed` does for the RSS `url`.

The repository has no tests, so the proof is the build. The agent runs `npm ci` and `npm run build`, then reads `public/hello-world/index.html` and `public/index.html` to show the script tags are present with the right `@type`, `headline` and `datePublished`, and runs `npx prettier --check` on the changed files since the `format` script uses Prettier. It pastes the JSON-LD from the built HTML in the pull request.

## Start it with one API call

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

```json
{
  "agent": "codex",
  "input": "Add structured data to this Gatsby blog and open a pull request. Read package.json, gatsby-config.js, gatsby-node.js, src/components/seo.js, src/templates/blog-post.js, src/pages/index.js and content/blog/hello-world/index.md first. Add an optional schema prop to the Seo component that renders a script tag of type application/ld+json with JSON.stringify of the object. In blog-post.js, add a raw ISO date field to the page query beside the formatted one and build a BlogPosting object in Head with headline, datePublished, description, author as a Person from siteMetadata.author.name, url and mainEntityOfPage from siteUrl joined with fields.slug without a double slash, and publisher from the site title. In src/pages/index.js build a WebSite object with name, url and description. Keep the existing microdata attributes. Run npm ci and npm run build, show the script tags from public/index.html and public/hello-world/index.html in the pull request, and run npx prettier --check on the changed files. Do not change gatsby-config.js values, the feed plugin or the post content.",
  "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

What comes back is a pull request that changes `src/components/seo.js`, `src/templates/blog-post.js` and `src/pages/index.js`, and nothing else. The description shows the `BlogPosting` script from `public/hello-world/index.html` and the `WebSite` script from `public/index.html` as built in the sandbox, and the output of `gatsby build` and `prettier --check`.

The starter has no workflow, so the build output in the pull request is the check. On a blog deployed from a `gatsby build` step, that step runs on the pull request's branch and fails if a query field is misspelled.

A reviewer checks that `datePublished` is the ISO date and not the display string, that `url` has no double slash, that the author name comes from `siteMetadata` rather than a literal, and that the microdata on the article element is still there. Then they paste one built page into a structured data validator before merging.

## Run it on every blog without JSON-LD

A team that runs several Gatsby sites sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `gatsby-config.js` and templates, so a site whose posts carry an `author` in frontmatter uses that instead of the site author, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request and the built JSON-LD from.

## Why run it on Rush?

Structured data is easy to add and easy to get subtly wrong: a formatted date where an ISO one is expected, a URL with a double slash, a field the page query never asked for. In a Rush sandbox the agent runs `gatsby build` and reads the HTML it produced, so the pull request shows the JSON-LD as a crawler will see it, and every command and its output stays in the run's record.

The starter has no tests, so on a laptop the check is a manual build and a look at the output. The agent does that for every page type it touched, and the same request works unchanged on the next Gatsby site a team runs.

## Frequently asked questions

### Why JSON-LD when the template already has microdata?

The microdata marks the article element with `schema.org/Article` and `headline`, but carries no date, author or URL. JSON-LD in `Head` can state all of them from the page query without changing the markup, and the existing attributes stay for anything that reads them.

### Where does the author come from?

From `siteMetadata.author.name` in `gatsby-config.js`, the same value `src/components/bio.js` shows under each post. A blog whose frontmatter carries a per-post author would read that field instead, which the agent does when it finds one.

### Does it need a plugin?

No. Gatsby 5's `Head` export renders any element into the document head, so one `<script type="application/ld+json">` in the `Seo` component does the job without `react-helmet` or a schema plugin.

### How is it checked without tests?

The agent runs `npm run build` and reads the script tag out of the generated `public/` HTML for a post page and the index, pasting both into the pull request. A reviewer can drop that HTML into a structured data validator.

## More Gatsby jobs

- [Add a Table of Contents to Gatsby Blog Posts from a Linear Issue](https://getrush.ai/run/add-table-of-contents/gatsby/)
- [Add Tag Pages to a Gatsby Blog from a Linear Issue](https://getrush.ai/run/add-tag-pages/gatsby/)
- [Convert a Gatsby Site From JavaScript to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/gatsby/)

## The same job on other stacks

- [Add JSON-LD Structured Data to a Hugo Documentation Site](https://getrush.ai/run/add-structured-data/hugo/)
- [Add JSON-LD Structured Data to a Jekyll Site](https://getrush.ai/run/add-structured-data/jekyll/)
- [Add Structured Data (JSON-LD) to a Nuxt App](https://getrush.ai/run/add-structured-data/nuxt/)

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