# 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 Rush](https://cloud.getrush.ai/run/add-open-graph-tags/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 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`

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

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

- [Add Reading Time to a Zola Blog](https://getrush.ai/run/add-reading-time/zola/)
- [Add Related Posts to a Zola Blog](https://getrush.ai/run/add-related-posts/zola/)
- [Add Search to a Zola Site](https://getrush.ai/run/add-search/zola/)

## The same job on other stacks

- [Add Open Graph and Twitter Card Tags to an Eleventy Blog](https://getrush.ai/run/add-open-graph-tags/eleventy/)
- [Add Open Graph and Twitter Card Tags to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-open-graph-tags/jekyll/)
- [Add Open Graph Tags to a Leptos App](https://getrush.ai/run/add-open-graph-tags/leptos/)

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