All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading