# Add Structured Data to a Pelican Blog

Yes. An agent adds JSON-LD BlogPosting markup to every article of your Pelican blog from its metadata, parses the built pages to check it, and opens a PR.

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

## What the agent does

The agent reads the settings and the theme together, because on Pelican the markup is a template and every value in it comes from a setting or an article's metadata. In a blog like getpelican/pelican-blog, `pelicanconf.py` sets `AUTHOR = "Pelican Contributors"`, `SITENAME`, `TIMEZONE = "Europe/Rome"`, `DEFAULT_LANG = "en"`, `THEME = "themes/notmyidea"` and an empty `SITEURL`, and `publishconf.py` imports all of that and sets `SITEURL` to the production address. The theme is a copy kept in the repository, so it can be edited: `templates/base.html` has a `title` block and a `content` block and nothing else to extend in `<head>`, `article.html` renders the title, `article_infos.html` and `article.content`, and `article_infos.html` already prints `article.date.isoformat()` into an `abbr` title. The nineteen files under `content/news/` are reStructuredText with a `:date:` field and, in most, a `:slug:`, except one Markdown post that also carries `Modified`; two name an author, one has tags and none sets a summary.

From that it writes the markup where the theme allows. It adds an empty `extra_head` block to `base.html` and fills it in `article.html` with one `application/ld+json` script. The object is built as a Jinja dictionary and printed with the `tojson` filter, so a quote or an angle bracket in a title cannot break the script: `@type` `BlogPosting`, `headline` from `article.title|striptags`, `datePublished` from `article.date.isoformat()`, `dateModified` from `article.modified` only when the post has one, `author` from `article.author` with the URL of its author page, `inLanguage` from `article.lang`, `description` from the stripped summary Pelican derives from the opening of the text, and `url` and `mainEntityOfPage` from `SITEURL` and `article.url`. The publisher is the site name with the touch icon that `EXTRA_PATH_METADATA` already copies to the root, since the logo files under `content/logo/` are not in `STATIC_PATHS` and never reach the output.

The two settings files matter for the check. With the development settings `SITEURL` is empty and every URL in the markup would be relative, which a crawler cannot use, so the template leaves `url` and `mainEntityOfPage` out when `SITEURL` is empty and the agent validates against the publish build. The repository has no requirements file, so in its sandbox the agent installs Pelican with its Markdown extra, records the version, and builds twice: `make html` and `make publish`, the Makefile targets that run `pelican` with `pelicanconf.py` and `publishconf.py`.

Then it reads what was built. A short script walks `output/`, pulls the script element out of each article page, parses it with `json.loads`, and checks that every article has a headline, an ISO 8601 `datePublished` carrying the Rome offset, an absolute `url` under the production address in the publish build and none in the development build, and that `dateModified` appears on the one post that declares it. It confirms the index, category and page templates gained no script. The Makefile's `serve` target calls `python -m SimpleHTTPServer`, which Python 3 does not have, so the agent serves `output/` with `python -m http.server` to look at one article in a browser and leaves that target for a separate change.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add JSON-LD structured data to the article pages of this Pelican blog. Read pelicanconf.py, publishconf.py, the Makefile, every template under the theme directory, and the metadata block of every file under content/ first. Add an extra_head block to the theme's base.html and fill it from article.html with one application/ld+json script of type BlogPosting, built as a Jinja dictionary and printed with tojson. Take headline, datePublished, dateModified, author, language and description from the article object, and url and mainEntityOfPage from SITEURL and article.url; omit the two URL fields when SITEURL is empty, and omit dateModified when the post has none. Use the site name as publisher with an image that is actually copied to the output. Install Pelican with Markdown support in your sandbox and report the version. Build with make html and with make publish, then write a script that extracts and parses the script element from every article page in both builds and checks the fields against each post's source metadata. Confirm that index, category, tag and page output has no script. Open a pull request with the script's output for both builds and one article's markup quoted in full.",
  "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 changes two theme templates, `base.html` and `article.html`, and adds the small checking script if the reviewer wants to keep it. No setting moves and no content file is edited. The description quotes one article's JSON-LD in full from the publish build, shows the checker's result for all articles in both builds, names the Pelican version used, and lists which optional fields each post ended up with.

A reviewer pastes the quoted markup into the validator they trust, checks that the author of a post with no `:author:` field is the site default they expect, and decides whether the publisher image is the right one. After merging, the markup appears the next time the site is published with `publishconf.py`; nothing has to be added to new posts for them to get it.

## Run it on every Linear issue labelled seo

Create an automation in the Project that holds the blog's repository, with this prompt and a `linear` trigger whose `labels` include the label your team uses for search work. When someone in your Rush org adds that label to an issue, a run starts and the issue is placed after the prompt as third-party data. The prompt stays the only instruction, so the issue can add context, such as which pages matter most, without rewriting the task. The trigger needs a Linear connection for the automation's runner, made in the console under Settings → Connections.

The automation's `max_runs_per_hour` caps how many runs a burst of labelled issues can start; an event past it waits as a `queued` run. For several blogs, a handler on your own server can send this body to `POST /o/{org}/sessions` once per repository, each with a `request_id` that is a UUID v5 of the repository name.

## Why run it on Rush?

Structured data is easy to write and easy to get subtly wrong: a relative URL, a date with no offset, a title with a quote that ends the string early. None of those shows up in the template; they show up in the built HTML. The agent builds the site twice in its own sandbox, parses every article's script, and keeps the build logs and the checker's output in the run's record, so the pull request shows parsed markup for each post.

The same request works for a blog on a theme installed from a package, where the template has to be overridden through `THEME_TEMPLATES_OVERRIDES` instead of edited in place, and for one whose posts carry tags, summaries and cover images that map to more properties. Each run reads the metadata the posts really have and leaves out fields it cannot fill.

## Frequently asked questions

### Do I have to add anything to each post?

No. Every value comes from metadata Pelican already has: title, date, slug, the default or per-post author, and the summary it derives from the text. A post that adds `Modified` gets `dateModified`; one without it simply has no such property.

### Why are the URLs missing when I build locally?

The development settings leave `SITEURL` empty, so any URL would be relative to nothing. The template omits `url` and `mainEntityOfPage` in that case and includes them in the build made with `publishconf.py`, where `SITEURL` is the real address. The checker verifies both behaviours.

### Will this work with a theme I installed instead of one in the repository?

The markup is the same, but the edit goes somewhere else. The agent copies the article template into a directory named by `THEME_TEMPLATES_OVERRIDES` and extends it there, so an update to the installed theme does not erase the change. It reports which approach it took.

### Does it validate against Google's rich results test?

The run parses the JSON and checks the properties against each post's source, which catches broken or missing values. It does not submit pages to an outside validator. The pull request quotes one article's markup in full so you can paste it into the tool you prefer.

## More Pelican jobs

- [Add a Typo Check to a Pelican Site](https://getrush.ai/run/add-typo-check/pelican/)
- [Add Dark Mode to a Pelican Blog](https://getrush.ai/run/add-dark-mode/pelican/)
- [Add a GitHub Pages Deploy Workflow to a Pelican Site](https://getrush.ai/run/add-deploy-workflow/pelican/)

## The same job on other stacks

- [Add Structured Data (JSON-LD) to a SvelteKit App](https://getrush.ai/run/add-structured-data/sveltekit/)
- [Add Structured Data to a VitePress Blog](https://getrush.ai/run/add-structured-data/vitepress/)
- [Add Schema.org Structured Data to a Wagtail Site](https://getrush.ai/run/add-structured-data/wagtail/)

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