# Add JSON-LD Structured Data to a Zola Site

Yes. An agent adds a JSON-LD partial to a Zola theme, a BlogPosting per post and a WebSite for the index, builds the site and checks every block parses.

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

## What the agent does

The agent starts from the one template every page passes through. In a Zola site on the even theme, like getzola/even, `templates/index.html` is the base: `page.html`, `about.html` and the taxonomy templates under `tags/` and `categories/` extend it, and its `<head>` holds a `<meta name="description">` that falls back from `page.description` to `config.description`, a `{% block title %}` that `page.html` overrides as `{{ config.title }} - {{ page.title }}`, feed links driven by `config.generate_feeds` and `config.feed_filenames`, and an empty `{% block extra_head %}`. There is no `application/ld+json` block anywhere in `templates/`, so search engines see the page's text and nothing about what kind of page it is.

Then it reads what each page knows about itself. `templates/post_macros.html` prints `page.date | date(format="%F")` and `page.category`; `page.html` renders `page.taxonomies.tags` as links and `page.lower` and `page.higher` for navigation. `config.toml` sets `base_url`, `title`, `description`, `generate_feed = true`, two taxonomies `categories` and `tags` with feeds, and `[extra] author = "Vincent"` beside `even_title` and the menu. Every post under `content/` carries `+++` front matter with `title`, `date` and a `[taxonomies]` table with `categories` and `tags`, and a `<!-- more -->` marker that gives Zola a `summary`. `theme.toml` says `min_version = "0.17.0"`, and `.github/workflows/docs.yml` builds the demo with `shalzz/zola-deploy-action@v0.17.2` on every push to `master`.

The agent adds `templates/structured_data.html` and includes it in the base head. When `page` is defined it emits a `BlogPosting` with `headline` from `page.title`, `datePublished` from `page.date` formatted as `%Y-%m-%d`, `dateModified` from `page.updated` when set and `page.date` otherwise, `url` and `mainEntityOfPage` from `page.permalink`, `description` from `page.description` or the stripped `page.summary`, `keywords` joined from `page.taxonomies.tags`, `articleSection` from the first category, and `author` as a `Person` named from `page.authors` when the post sets them and `config.extra.author` otherwise. When `section` is defined instead it emits a `WebSite` with `name`, `url` and `description` from the config. Every value passes through Zola's `json_encode` filter, so a title with a quote or an apostrophe produces valid JSON instead of breaking the block, and the partial writes nothing on a taxonomy page with neither variable.

To prove it, the agent downloads the Zola release matching `theme.toml`'s minimum or newer into its sandbox, runs `zola check` and `zola build`, and runs a short script over every HTML file under `public/` that finds each `<script type="application/ld+json">`, parses it with a JSON parser and prints the `@type`, so the pull request shows one `BlogPosting` per post and one `WebSite` for the index with no parse error. It also pastes the block from one built post so a reviewer can paste it into a validator.

## 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 Zola site. Read config.toml, theme.toml, templates/index.html, templates/page.html, templates/post_macros.html, templates/about.html, the templates under tags/ and categories/, three files under content/ and .github/workflows/docs.yml first. Add templates/structured_data.html and include it in the base template's head: when page is defined emit a BlogPosting with headline, datePublished, dateModified falling back to the date, url, mainEntityOfPage, description from page.description or the stripped summary, keywords from the tags, articleSection from the first category and author as a Person from page.authors or config.extra.author; when section is defined emit a WebSite from the config; emit nothing otherwise. Pass every value through json_encode. Install a Zola release at or above the theme's min_version in your sandbox, run zola check and zola build, then run a script that parses every application/ld+json block under public/ and prints its @type, and paste that output and one built post's block into the pull request. Change no content file and no stylesheet.",
  "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 `templates/structured_data.html` and changes `templates/index.html` by one include line, with nothing under `content/`, `sass/` or `static/` touched. Its description shows the `zola check` and `zola build` output, the script's list of every page's `@type` with no parse failure, and the complete block from one built post.

Each post now describes itself as a `BlogPosting` with its real date, tags, category and author, and the index as a `WebSite`; taxonomy pages carry no block rather than a wrong one. The rendered pages are otherwise byte-for-byte what the theme produced, since the partial only adds a `<script>` to the head, and the demo deploy on `master` keeps working because the workflow and the build are unchanged.

Before merging, a reviewer decides whether `config.extra.author` is the right fallback or whether every post should name its authors, chooses whether to add a `publisher` with a logo for rich results, and pastes the quoted block into a validator to see what a search engine would read.

## Run it on every Linear issue labelled seo

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled` with the label your search work uses in its `labels`. Each labelled issue starts one run with the issue as its context, on its own branch; the trigger adds the issue after the prompt and fills in no placeholder, and a change made by an app integration never fires it, so the agent's own comment on the issue starts nothing.

The automation's `max_runs_per_hour` holds a burst of labels to that many runs an hour: a fire past it is created `queued` and starts when the hour has room, and one past a second hour's worth is skipped as `rate_limited` until the issue is labelled again. From your own server, the same run starts with this request and the issue URL in `resources`, with a `request_id` that is a UUID v5 of the issue id so a retried start returns the run already begun.

## Why run it on Rush?

Structured data fails quietly: a template that renders fine can emit a block that no parser accepts, and nothing on the page shows it. The agent builds the whole site in its own sandbox and parses every block it produced, so the pull request proves the output rather than the template, and the one post it quotes is the real rendered block.

The transcript keeps the Zola install, the build and the parse script with their output, so a reviewer reads the evidence from one page without building locally. Several Zola sites on the same theme can be given the partial at once, each run in its own sandbox with its own Zola binary, and nothing merges until a person reads the diff.

## Frequently asked questions

### Why a separate partial instead of editing the head directly?

The base template's head is shared by every page type, and a partial keeps the JSON-LD logic in one file that `page.html` and the taxonomy templates never need to know about. It is also the only file a site that overrides the theme has to copy to adjust the markup.

### What stops a title with a quote from breaking the JSON?

Every value goes through Zola's `json_encode` filter, which quotes and escapes the string, rather than being written between hand-typed quotes. The parse script the agent runs over `public/` is the check that this held for every post in the site.

### Does this change what the Open Graph tags say?

No. JSON-LD is a separate block read by search engines, and this change does not add or alter any `og:` or `twitter:` meta tag. A site that already has them keeps them; one that wants them is a separate change with its own page.

### Will it work on an older Zola?

The partial uses `date`, `json_encode`, `striptags` and the `page` and `section` variables, all of which exist at the theme's declared minimum. The agent builds with a release at or above that minimum and names the exact version in the pull request, so a reviewer can match it to their deploy action.

## More Zola jobs

- [Add a Table of Contents to Zola Posts](https://getrush.ai/run/add-table-of-contents/zola/)
- [Add a Typo Check to a Zola Site](https://getrush.ai/run/add-typo-check/zola/)
- [Add a Build Check for Every Pull Request to a Zola Site](https://getrush.ai/run/add-build-check/zola/)

## The same job on other stacks

- [Add JSON-LD Structured Data to an Eleventy Blog](https://getrush.ai/run/add-structured-data/eleventy/)
- [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/)

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