# Add JSON-LD Structured Data to an Eleventy Blog

Yes. An agent adds a JSON-LD block to your Eleventy layouts, a BlogPosting per post and a WebSite for the rest, builds the site and checks every page's block parses.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the layout chain and the data behind it. In a blog like 11ty/eleventy-base-blog, every page renders through `_includes/layouts/base.njk`, whose `<head>` has a `<title>` of `{{ title or metadata.title }}`, a `description` meta tag and the Atom feed link, and nothing else about the page; posts go through `_includes/layouts/post.njk`, which sets `layout: layouts/base.njk` and prints the title, the date through the `readableDate` and `htmlDateString` filters from `_config/filters.js`, and the tags. `content/blog/blog.11tydata.js` gives every post `tags: ["posts"]`, and each post's front matter, as in `content/blog/firstpost.md`, carries `title`, `description`, `date` and `tags`. Site-wide values are in `_data/metadata.js`: `title`, `url` (still `https://example.com/`), `language`, `description` and an `author` with `name`, `email` and `url`.

The agent adds one include, `_includes/jsonld.njk`, and one line in `base.njk` that pulls it into the `<head>`. The include builds a plain object in Nunjucks and prints it with the `dump` filter inside `<script type="application/ld+json">`, so there is no hand-written JSON to break. On a page whose `tags` include `posts` it emits a `BlogPosting` with `headline` from `title`, `description`, `datePublished` from `page.date | htmlDateString`, `url` and `mainEntityOfPage` from `page.url | htmlBaseUrl(metadata.url)`, the same filter `content/sitemap.xml.njk` already uses for absolute URLs, `keywords` from the tags with `all` and `posts` removed by the existing `filterTagList` filter, and an `author` of type `Person` from `metadata.author`. On every other page it emits a `WebSite` with `name`, `url` and `description` from `metadata`, and the home page, `content/index.njk`, additionally gets a `Blog` whose `blogPost` list is the posts the page shows.

An optional `image` front matter key becomes `BlogPosting.image` as an absolute URL, and because `_data/eleventyDataSchema.js` already validates the `draft` key with a Zod schema, the agent extends that schema with `image: z.optional(z.string())` so a typo fails the build the way an invalid `draft` does. `datePublished` uses the post's `date`, and `dateModified` is left out rather than invented, since the repository does not track modification dates; the pull request says how to add one from Git if wanted. The include is wrapped so a page that sets `eleventyExcludeFromCollections`, such as the tag pages from `content/tag-pages.njk`, still gets a `WebSite` block and nothing more.

The proof is the built output. The agent runs `npm install` and `npm run build`, which is `npx @11ty/eleventy` on the Node 22 that `.nvmrc` pins, then runs a short Node script over `_site/**/index.html` that extracts every `application/ld+json` block, parses it, and checks the `@type` matches the page kind and that `url` is absolute. It reads `_site/blog/firstpost/index.html`, `_site/index.html` and `_site/tags/second-tag/index.html` in full and quotes the three blocks in the pull request. `metadata.url` stays as it was found; the pull request repeats the caveat the sitemap already carries, that the URLs are right once that value is the real domain.

## 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 Eleventy blog. Read the layouts, the global data, the filters and one post first. Add an include that emits one application/ld+json block per page from Nunjucks data with the dump filter: a BlogPosting for pages tagged posts, with headline, description, datePublished, absolute url, keywords and author from the site metadata; a WebSite for other pages; and a Blog listing the posts on the home page. Support an optional image front matter key and validate it in the existing data schema. Do not invent a modification date. Build the site, parse every emitted block with a script and check its type and that its url is absolute, and quote the blocks for a post, the home page and a tag page in the pull request. 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

What comes back is a pull request on its own branch that adds `_includes/jsonld.njk`, changes `_includes/layouts/base.njk` by one include line and `_data/eleventyDataSchema.js` by one schema key, and documents the `image` key with an example in one post. The description quotes the three emitted blocks, a `BlogPosting`, a `WebSite` with a `Blog`, and a tag page's `WebSite`, and the script's summary of how many pages were checked and that every block parsed.

The run's record keeps the build output and the check script with its results, so a reviewer can see the blocks came out of a real build of this site and that no page emits invalid JSON.

Before merging, a reviewer pastes one built post into Google's Rich Results Test or the Schema Markup Validator, since the agent checks that the JSON is well formed and typed and not how a search engine will treat it, sets `metadata.url` to the real domain if that has not happened yet, and decides whether `dateModified` from Git is worth the build-time cost the description outlines.

## Run it on every blog repository

This is a one-time change per site, started from a terminal with `POST /o/{org}/sessions`, this body and the repository in `resources`. The run keeps going in its sandbox after you close the window, and a follow-up through `POST /o/{org}/sessions/{id}/messages` can add `BreadcrumbList` to the posts or an `Organization` publisher without rebuilding from scratch. After the merge, every new post gets its block from its own front matter.

A studio that maintains several Eleventy sites starts one run per repository from a script with the same body, each with its own `request_id`, a UUID, so a retried start returns the run it already began; the key's `webhook_url` receives `run.completed` for each with a `session_url` from which the handler reads the pull request link.

## Why run it on Rush?

Structured data fails quietly: a trailing comma, a relative URL or a `datePublished` in the wrong format leaves the block ignored and nobody notices until a rich result never appears. The agent generates the block from data with a filter that cannot emit broken JSON, builds the site and parses every page's block back, so the pull request shows that the output is valid rather than hoping.

The build and the check run in a disposable sandbox with the Node version the repository pins, the output stays with the run, and several sites can be done at once, each with its own pull request and its own quoted blocks.

## Frequently asked questions

### Will this change the visible page?

No. The block is a `<script type="application/ld+json">` in the `<head>`, which browsers do not render. Nothing in the body, the CSS bundle or the existing meta tags changes.

### Why is there no dateModified?

The repository tracks only the post's `date`, and inventing a modification date would be wrong more often than right. The pull request describes how to compute one from the file's last Git commit with a filter, at the cost of a Git call per page at build time, and leaves that choice to you.

### Does it validate against schema.org?

It checks that every block parses, has the expected `@type` for the page kind and an absolute `url`. Whether a search engine accepts it is checked by pasting a built page into the Rich Results Test, which the description asks the reviewer to do once.

### What about the example.com URLs?

They come from `metadata.url`, which the starter leaves as `https://example.com/`, and the sitemap already has the same dependency. The agent does not guess your domain; set that value and every absolute URL in the blocks follows.

## More Eleventy jobs

- [Add a Table of Contents to Eleventy Blog Posts](https://getrush.ai/run/add-table-of-contents/eleventy/)
- [Add a Typo Check to an Eleventy Blog in CI](https://getrush.ai/run/add-typo-check/eleventy/)
- [Add Webmentions to an Eleventy Blog](https://getrush.ai/run/add-webmentions/eleventy/)

## The same job on other stacks

- [Add Structured Data to a Gatsby Blog](https://getrush.ai/run/add-structured-data/gatsby/)
- [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/)

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