# Add Open Graph Tags to an mdBook Site

Yes. An agent adds Open Graph and Twitter card tags to your mdBook's theme/head.hbs from the variables the renderer passes, checks the built HTML, and opens a PR.

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

## What the agent does

The agent reads the theme and the build before it writes a tag, because mdBook renders `head.hbs` as a Handlebars partial with a fixed set of variables and anything else comes out empty. In a book laid out like rust-lang/rust-by-example, `theme/` overrides only `head.hbs` and `css/language-picker.css`; `head.hbs` is one `<script>` that builds a language menu from `{{ path }}` and `{{ path_to_root }}` and reads the `lang` attribute at runtime. `book.toml` sets `title`, `description`, `git-repository-url`, `edit-url-template` and `hash-files` under `[output.html]`, and has no `site-url`. `.github/workflows/rbe.yml` pins mdBook `0.5.1`, runs `mdbook test`, `mdbook build`, a link check, and then one build per translation with `MDBOOK_BOOK__LANGUAGE` set to each of `ja`, `zh`, `es` and `ko` into `book/<lang>`, from the `.po` files under `po/`.

It then reads the renderer at that version, `crates/mdbook-html/src/html_handlebars/hbs_renderer.rs` at the `v0.5.1` tag, to learn what `head.hbs` can use: `language`, `book_title`, `description`, `title` (the chapter name joined to the book title), `chapter_title`, `path` (the Markdown file, such as `hello/print.md`), `path_to_root` and `git_repository_url`. `base_url` from `site-url` is passed only to the 404 page, and there is no helper that rewrites `.md` to `.html`. The tags are therefore `og:title` from `{{ title }}`, `og:site_name` from `{{ book_title }}`, `og:description` from `{{ description }}`, `og:type` `website`, `og:locale` from `{{ language }}` mapped with the built-in `eq` helper to `ja_JP`, `zh_CN`, `es_ES`, `ko_KR` and `en_US`, and `twitter:card` `summary`. `og:url` is left out on purpose and the pull request says why: the template has the Markdown path, not the page URL, and crawlers fall back to the fetched address.

For the image, the agent adds a card PNG under `src/`, which mdBook copies into the output, and sets `og:image` to the deployed book address joined with the file, with `og:image:width`, `og:image:height` and `og:image:alt`; the address itself comes from the prompt or from the README's link to the published book, since the renderer offers no site URL variable. The new tags go above the existing script in `head.hbs`, which is unchanged.

Then it builds the way CI does: `mdbook build`, then `MDBOOK_BOOK__LANGUAGE=ja mdbook build -d book/ja` with `mdbook-i18n-helpers` installed as `rbe.yml` installs it, and reads `book/hello/print.html` and `book/ja/hello/print.html` to check that `og:title` carries the chapter name, `og:description` the book description, and `og:locale` the right value per build. It runs `mdbook test` too, since the workflow does, and pastes the relevant `<head>` lines into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Open Graph and Twitter card tags to this mdBook site. Read book.toml, theme/head.hbs, theme/css, src/SUMMARY.md, README.md and .github/workflows/rbe.yml first, then read the HTML renderer source of the mdBook version the workflow pins to learn which variables head.hbs receives. Add og:title, og:site_name, og:description, og:type, og:locale and twitter:card meta tags to theme/head.hbs using only variables the renderer passes, mapping the language variable to a locale with the eq helper for each translation the workflow builds. Add a 1200 by 630 card image under src and reference it with an absolute og:image URL built from the published book address in the README. Leave og:url out if the template cannot produce a page URL and say so. Run mdbook build for the default language and one translation and check the generated head of one chapter in each. Run mdbook test as the workflow does. Open a pull request with the head excerpts and the command output.",
  "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 changes `theme/head.hbs` and adds one image under `src/`. Its description quotes the rendered `<head>` of one chapter from the English build and one from a translation, lists each tag and the variable it comes from, and explains the missing `og:url`.

`CI` runs on the pull request as before: tests, the English build, the link check and the four translation builds, none of which the new tags affect; the image adds one file to the uploaded `rust-by-example` artifact.

Before merging, a reviewer checks the published address the image URL uses, reads one chapter's tags in a card validator once the preview is deployed, and decides whether a per-chapter description is wanted, which would need a preprocessor since `description` is the book's.

## Run it on every documentation site without social cards

A team with several mdBook sites starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that repository in `resources`, the published address in `input`, and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `book.toml` and pinned mdBook, so a book with `language` set and no translations gets a fixed locale, and one that already overrides `index.hbs` gets the tags placed in that file instead of a new `head.hbs`.

A team that files site work in Linear runs the same prompt from an automation in the Project with a `linear` trigger on issues labelled `docs`. The trigger adds the issue after the prompt, so an issue that attaches the card image or names the address reaches the agent with it, and the pull request links back to the issue.

## Why run it on Rush?

The whole job depends on which variables one partial receives from one version of a renderer, and the honest way to find out is to read that version's source and build the book. The agent does both in its own sandbox, with the exact mdBook and `mdbook-i18n-helpers` versions the workflow pins, and reads the generated HTML rather than assuming the tags rendered.

The English build, a translation build and `mdbook test` all run before the pull request opens, and their output stays with the run, so a reviewer sees the rendered head without building the book. For a team with several books, each gets its own run and its own pull request, fitted to its own theme and pinned version.

## Frequently asked questions

### Why is there no og:url?

Because `head.hbs` receives `path`, which is the Markdown source path such as `hello/print.md`, and mdBook's Handlebars has no helper to rewrite it to the `.html` page, while `site-url` is only passed to the 404 page. Crawlers use the address they fetched when `og:url` is absent. A preprocessor could add a page URL variable; the pull request names that as the way to get one.

### Will the tags be right on the translated builds?

Yes, within what the renderer knows. Each translation is a separate `mdbook build` with `MDBOOK_BOOK__LANGUAGE` set, so `{{ language }}` is `ja`, `zh`, `es` or `ko` in that build and the `eq` mapping picks the matching `og:locale`; the agent builds one translation to show it. Titles stay in the source language unless the chapter names are translated in the `.po` file, which the gettext preprocessor handles as it does today.

### Does this change the language picker?

No. The existing script in `head.hbs` is kept as it is, below the new tags. Meta tags are static HTML so crawlers that do not run JavaScript see them, which is also why the tags cannot reuse the script's path logic.

### Where does the image come from?

From the prompt when a team has one; otherwise the agent draws a plain card with the book title at 1200 by 630 and puts it under `src/`, which mdBook copies to the output. The reviewer can swap the file without touching the template.

## More mdBook jobs

- [Add PDF Export to an mdBook Book](https://getrush.ai/run/add-pdf-export/mdbook/)
- [Add Redirects for Moved Pages to an mdBook](https://getrush.ai/run/add-redirects/mdbook/)
- [Add a Sitemap to an mdBook Site](https://getrush.ai/run/add-sitemap/mdbook/)

## The same job on other stacks

- [Add Open Graph Tags to a Pelican Blog](https://getrush.ai/run/add-open-graph-tags/pelican/)
- [Add Open Graph Tags to Sphinx Docs](https://getrush.ai/run/add-open-graph-tags/sphinx/)
- [Add Open Graph Tags to a VitePress Blog](https://getrush.ai/run/add-open-graph-tags/vitepress/)

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