All jobs

Add Open Graph Tags to a Zola Site

Yes. An agent reads your Zola theme's base template and front matter, adds Open Graph and Twitter card tags to every page type, builds the site 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 starts from the template every page inherits. In a Zola site on the even theme, like getzola/even, that is templates/index.html: page.html, about.html, tags/single.html and categories/list.html all extend it, so its <head> is the one place a social tag can go. That head already carries a <meta name="description"> that falls back from page.description to config.description, a <title> block that page.html overrides as {{ config.title }} - {{ page.title }}, and an empty {% block extra_head %}. There is no og: or twitter: tag anywhere in the theme. The agent also reads config.toml (base_url, title, description, [extra] author) and theme.toml, whose min_version = "0.17.0" and whose deploy workflow, shalzz/zola-deploy-action@v0.17.2, fix which Zola the tags must build under.

Then it checks what the content can supply. The posts sit at the root of content/ with title, date and [taxonomies] in their front matter and a <!-- more --> marker that gives each one a page.summary; none of them sets description, and only markdown_overview.md embeds an image. content/_index.md paginates by date, and content/pages/about.md renders through about.html with path = "about". So the agent writes a templates/og.html that index.html includes after the description meta, with one branch per context Tera exposes: a page gets og:type article, og:title from page.title, og:description from page.description when set and otherwise from page.summary stripped of HTML and truncated, og:url from page.permalink, article:published_time from page.date, article:author from config.extra.author and article:tag for each entry in page.taxonomies.tags; a section or a taxonomy term gets og:type website with its own permalink; and every page gets og:site_name from config.title and og:locale from the lang attribute the template already sets. An og:image is written only when page.extra.image or a new config.extra.og_image names one, resolved through get_url, and twitter:card switches between summary and summary_large_image on the same condition, because a card that points at a missing file is worse than none.

One thing it finds on the way is that the head is already out of step with the config. config.toml sets generate_feed = true, the 0.17 name, while the feed <link> in index.html tests config.generate_feeds and loops over config.feed_filenames, the names Zola introduced later. Built with 0.17.2 the site writes atom.xml but no page carries a rel="alternate" link to it, and the current Zola release refuses the config outright with unknown field generate_feed. The agent leaves that decision to the maintainer but names it in the pull request, and it writes the new tags with names that exist in 0.17 (page.permalink, page.summary, config.base_url, get_url) rather than anything newer, so they render under the version the workflow pins.

To check the result, the agent downloads the 0.17.2 release the deploy action uses, runs zola build on the demo site, which produces the same count of pages as before, and reads the output: public/first-post/index.html must carry an article block with a date and the two tags from its front matter, public/index.html a website block, public/tags/tag1/index.html the taxonomy permalink, and public/about/index.html the about page's own title. It runs zola check, serves public/ and opens three pages in its own browser to confirm nothing in the layout changed, since the include adds only <meta> elements. A post with a description in its front matter and one with extra.image are added to the demo content as examples, so the pull request shows both branches rendering.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Open Graph and Twitter card meta tags to this Zola site. Read config.toml, theme.toml, the templates directory (the base template every other template extends, and which contexts each template receives: page, section or term), the content front matter, and the deploy workflow to learn which Zola version builds the site. Add a template partial that the base template includes in its head, with og:type article for pages and website for sections and taxonomy pages, og:title, og:description falling back from the page description to its summary, og:url from the permalink, og:site_name, og:locale, article:published_time, article:author and article:tag from the front matter and config, and og:image plus twitter:card only when a page or the config names an image. Use only template variables the pinned Zola version supports. Install that version, build the site, read the generated HTML for a post, the index, a tag page and a standalone page, run zola check, and open a pull request that quotes the tags from the generated files and lists anything in the existing head that the pinned version does not render.",
  "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 one partial under templates/, one {% include %} line in the base template's head, and the og_image key under [extra] in config.toml with a comment saying it is optional. Its description quotes the <meta> block from a generated post page and from the generated index, shows the zola build and zola check output, and lists the Zola version it built with and why that version was chosen.

A reviewer checks that the description fallback reads well for a post with no description in its front matter, since the summary is the first paragraph up to the <!-- more --> marker, and decides whether to add a site-wide image so cards get a picture. After merging, the next push runs the pinned deploy action and every page on the published site carries the tags; a link pasted into Slack or Mastodon then unfurls with the post's own title and date instead of the bare URL.

Run it on every Linear issue labelled seo

A team that tracks site work in Linear adds an automation to the Project with a linear trigger on linear.issue.labeled, the label seo, with the automation set to read only. Each labelled issue starts a read-only run that reads the theme and posts, as a comment on the issue, which template it would change, which front-matter keys the posts already have and which tags would therefore be empty. Only a change made by a member of the Rush org fires the trigger, and that comment is the whole result, because an automation's runs push nothing.

When the plan is agreed, a handler on the team's own server sends this body with the issue's URL added to resources, which puts the issue text in front of the agent through the team's Linear connection, and a request_id that is a UUID v5 of the issue id, so a second delivery of the same event returns the run already started instead of opening a second pull request.

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

Why run it on Rush?

The hard part of this job is not writing six <meta> lines; it is knowing which template context each page type gets, which front-matter keys the content actually sets, and which template variables the Zola version in the deploy workflow understands, since a tag that reads a variable 0.17 lacks renders as nothing. The agent reads all three from the repository, builds with the pinned release in its own sandbox, and keeps every command and its output in the run's record, so the pull request can quote the generated HTML rather than describe it.

It also fits the site rather than a generic snippet: page.summary as the description fallback because the posts use the more marker, config.extra.author because the theme already defines it, no image tag because the theme has no image to point at. A publisher with several Zola sites on several themes sends one request per repository and gets one pull request each, with the tags placed where that theme's base template puts its head.

Frequently asked questions

Will the tags work with the Zola version my site deploys with?

Yes. The agent reads the deploy workflow first and builds with the same release, so it uses only variables that version exposes. The pull request says which version it built with, and names anything in the existing head that the version does not render, such as a feed link guarded by a newer config name.

What goes in og:image when my posts have no images?

Nothing, unless you give it one. The partial writes og:image only when a page sets extra.image or config.toml sets extra.og_image, and it switches twitter:card to summary_large_image on the same condition. A tag pointing at a file that does not exist makes previews worse, so an absent image is left absent.

Does it change my theme's layout?

No. The change is an {% include %} inside the head of the base template plus the new partial, so only <meta> elements are added. The agent serves the built site and opens a few pages in a browser to confirm the rendered layout is unchanged.

Can I use it with a theme installed as a git submodule?

Yes. Zola lets a site override any theme template by placing a file with the same path under its own templates/, so the agent copies the theme's base template there and adds the include, leaving the submodule untouched. The pull request notes that a later theme update will not reach the copied file.

What about the description for the index and tag pages?

Those contexts have no page, so the partial falls back to config.description for the index and to the term or section name for a taxonomy or section page, with og:type website. The pull request shows the generated index head so you can judge the wording.

More Zola jobs

The same job on other stacks

Keep reading