# Add JSON-LD Structured Data to a Jekyll Site

Yes. An agent adds a BlogPosting and WebSite JSON-LD include built from the captures the head already makes, builds on both Jekyll versions and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-structured-data/jekyll/). 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 what the head already knows about each page. In a site built on daattali/beautiful-jekyll, `_includes/head.html` captures `pagetitle` from `page.share-title`, `page.title` or `site.title`, `description` from `page.share-description`, `page.subtitle` or the first words of the content, `author` from `page.author` or `site.author`, and `img` from `page.share-img`, `page.cover-img`, `page.thumbnail-img` or `site.avatar`, and writes them into `og:` and `twitter:` meta tags. It uses `page.id` to decide between `og:type` of `article` and `website`. There is no `<script type="application/ld+json">` anywhere and no `jekyll-seo-tag`: `_config.yml` lists only `jekyll-paginate` and `jekyll-sitemap`, and the gemspec depends on `jekyll >= 3.9.3`, with `Appraisals` testing 3.9.4 and 4.3.3 in `.github/workflows/ci.yml`.

It writes one new include, `_includes/structured-data.html`, and calls it from `head.html` after the captures, so the JSON-LD and the meta tags can never disagree. On a post, where `page.id` is set, it emits a `BlogPosting` with `headline` from `pagetitle`, `description`, `datePublished` from `page.date | date_to_xmlschema`, `dateModified` from `page.last-updated` when a post sets it, `author` as a `Person` named from the `author` capture, `image` from `img | absolute_url` when there is one, `keywords` from `page.tags`, `url` and `mainEntityOfPage` from `page.url | absolute_url`. On the home page it emits a `WebSite` with `name`, `url` and `description`; the theme's search in `_includes/search.html` runs in the browser with no query URL, so no `SearchAction` is claimed. Other pages get a `WebPage` with the same name and description.

The strings are the part that breaks silently, so the agent runs every value through `jsonify` instead of quoting by hand: a title with a quote, an apostrophe in a subtitle, or `strip_html` output with an ampersand would otherwise produce invalid JSON that search engines ignore without a visible error. The include stays plain Liquid, with no plugin, because this theme is distributed as a gem and used on GitHub Pages, where a new plugin is not always available; `jekyll-seo-tag` would do some of this, but it would also add its own title and meta tags beside the ones `head.html` already writes.

Then it builds the way CI does. `ci.yml` runs `bundle exec appraisal install` and `bundle exec appraisal jekyll build --future` with `JEKYLL_ENV=production`, so the agent runs both Jekyll versions from `Appraisals`. It reads `_site/2020-02-28-sample-markdown/index.html`, the sample post with `author: Bill Smith` and a `[test]` tag, extracts the script block and parses it with Ruby's `JSON.parse` to prove it is valid, then does the same for the home page and the about page. It uses its browser to paste the built post into the schema.org validator and records what the validator reports, and leaves the richer checks that need a live URL to the reviewer.

## 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 Jekyll site. Read _config.yml, the gemspec and Appraisals, _includes/head.html, the layouts, a post's front matter and _includes/search.html first. Write _includes/structured-data.html using the same captures head.html already makes for title, description, author and image, and include it from head.html after those captures. Emit a BlogPosting on posts (headline, description, datePublished, dateModified when last-updated is set, author as a Person, image when there is one, keywords from tags, url and mainEntityOfPage), a WebSite on the home page without a SearchAction unless the site has a search URL, and a WebPage elsewhere. Pass every value through jsonify; use no plugin. Build with both Jekyll versions the Appraisals file names, parse the script block out of a built post, the home page and a page and check it is valid JSON, check it in the schema.org validator with your browser, paste the output in the pull request and open it.",
  "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

A pull request that adds `_includes/structured-data.html` and one `include` line in `_includes/head.html`, with no change to `_config.yml`, the `Gemfile` or the gemspec. The description shows the JSON-LD block from the built sample post, the parse check for all three page kinds, the build output on both Jekyll versions and what the validator reported.

A reviewer compares the `BlogPosting` with the meta tags above it in the same built page: same headline, same description, same image. They decide two things the template cannot: whether `author` should carry a `url` for each writer, which the theme has no field for today, and whether a `publisher` with a logo should be added, which needs an image the site owner chooses.

They can also open the built post in Google's rich results test once it is deployed, since that tool needs a public URL; the pull request says the schema.org check was done on the built HTML.

## Run it on every blog repository

A company with several Jekyll sites runs this once per repository rather than by hand. A short script on your server lists the repositories and sends one `POST /o/{org}/sessions` per site with this body and that repository in `resources`. Give each request a `request_id`, a UUID made with UUID v5 from the repository name, so a retried run of the script returns the session it already started instead of opening a second pull request. Set a `webhook_url` on the key from the console's Developers page and each `run.completed` event names the session; read the pull request from it.

## Why run it on Rush?

The template is a few dozen lines of Liquid; the risk is a quote in one title breaking the JSON on one page out of hundreds, or a value that disagrees with the meta tags beside it. The agent builds the whole site in its own sandbox on both Jekyll versions the theme supports, parses the output rather than eyeballing it, and checks a built page in the validator with its own browser.

The two builds, the parse checks and the validator page stay in the run's transcript at `GET /o/{org}/sessions/{id}/messages`, and the new include is listed with its content at `GET /o/{org}/p/{project}/sessions/{id}/changes`. A reviewer who wants to see what a crawler will read copies it from there.

## Frequently asked questions

### Why not add jekyll-seo-tag?

It would work, but it writes its own `<title>` and Open Graph tags beside the ones `head.html` already produces from `share-title`, `share-description` and `share-img`, and a theme shipped as a gem would gain a plugin dependency its users have to allow. One include that reuses the existing captures adds the JSON-LD and nothing else.

### How are quotes and special characters in titles handled?

Every value goes through Liquid's `jsonify` filter, which produces a quoted, escaped JSON string. Writing `"{{ title }}"` by hand breaks on the first title with a double quote, and the page would carry invalid JSON that search engines drop silently.

### Does the home page get a SearchAction?

Not in this theme, because its search runs in the browser from `_includes/search.html` and there is no results URL with a query parameter to describe. The home page gets a `WebSite` with name, URL and description; a site that adds a server-side search page can add the action then.

### Will it build on GitHub Pages?

Yes. The include is plain Liquid with no plugin, and the agent builds it with the two Jekyll versions in `Appraisals`, which cover the version GitHub Pages runs. Nothing in `_config.yml` changes.

## More Jekyll jobs

- [Add a Table of Contents to Jekyll Posts](https://getrush.ai/run/add-table-of-contents/jekyll/)
- [Add Tag Pages to a Jekyll Blog](https://getrush.ai/run/add-tag-pages/jekyll/)
- [Add a Typo Check to a Jekyll Site in CI](https://getrush.ai/run/add-typo-check/jekyll/)

## The same job on other stacks

- [Add Structured Data (JSON-LD) to a Nuxt App](https://getrush.ai/run/add-structured-data/nuxt/)
- [Add Structured Data to a Pelican Blog](https://getrush.ai/run/add-structured-data/pelican/)
- [Add Structured Data (JSON-LD) to a SvelteKit App](https://getrush.ai/run/add-structured-data/sveltekit/)

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