All jobs

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

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading