# Add Social Preview Cards to a MkDocs Material Site

Yes. An agent turns on Material's social plugin, pins its image libraries, adds the system packages to CI and opens a PR with a generated card per page.

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

## What the agent does

The agent reads how the docs are built and published before it adds a plugin that draws images, because the plugin needs native libraries that a plain `pip install` does not bring. In a project laid out like encode/httpx, `mkdocs.yml` uses the `material` theme with a `custom_dir` of `docs/overrides` (one partial, `nav.html`, that adds a sponsor link), a light and dark palette, `site_url` set to the public address, `repo_url`, a four-section `nav`, the `admonition`, `codehilite` and `mkautodoc` extensions, and one stylesheet in `extra_css`. There is no `plugins` list, so the built-in search is on by default. `requirements.txt` pins `mkdocs` 1.6.1, `mkdocs-material` 9.6.18 and `mkautodoc` 0.2.0 among the tooling, `scripts/build` runs `python -m build`, `twine check` and `mkdocs build`, `scripts/publish` runs `mkdocs gh-deploy --force` on a tag, and `.github/workflows/test-suite.yml` runs those scripts on Python 3.9 through 3.13. `docs/img/` holds the butterfly logo and `docs/CNAME` the custom domain.

The agent adds a `plugins` list to `mkdocs.yml` with `search` first, because declaring the list turns the default off, then `social` with `cards_layout_options` that set the background and text colours to the palette's primary and a `cards_dir` of `assets/images/social`. It sets `theme.logo` to `img/butterfly.png` so the card carries the project mark, and adds a `description` to the front matter of `docs/index.md` and `docs/quickstart.md`, since the plugin takes a page's description from there and falls back to `site_description` otherwise. In `requirements.txt` it pins `pillow` and `cairosvg`, the two packages the `imaging` extra of Material installs, under the documentation group with a comment that says why. The plugin writes its cache to `.cache/`, so that goes into `.gitignore`.

On Ubuntu the plugin also needs Cairo, FreeType, libffi, libjpeg, libpng and zlib, so `test-suite.yml` and `publish.yml` gain an `apt-get install` step for the `-dev` packages before `scripts/install`. The docs job is the only one that needs them, but the test matrix runs `scripts/build` on every Python version, so the step is added once at the top of the job. `scripts/docs`, which serves the site locally, is left alone; a developer without the libraries can set `MKDOCS_SOCIAL=false` in an `enabled` key the agent adds to the plugin block, which Material reads as an environment variable.

To check it, the agent installs the system packages in its sandbox, runs `scripts/install` and `mkdocs build --strict`, lists `site/assets/images/social/` to count one PNG per page, opens `site/index.html` and reads the `og:image`, `og:description` and `twitter:card` tags the plugin injects, and views two of the cards to confirm the logo, title and colours rendered. It runs `scripts/check` as well, since the lint step covers the repository.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add social preview cards to this MkDocs Material site. Read mkdocs.yml, requirements.txt, scripts/build, scripts/install, scripts/publish, scripts/docs, .github/workflows/test-suite.yml, .github/workflows/publish.yml, docs/overrides/ and docs/index.md first. Add a plugins list that keeps search and enables the social plugin with layout colours from the palette and a cards directory under assets/images, set the theme logo from docs/img, add front-matter descriptions to the index and quickstart pages, pin pillow and cairosvg in requirements.txt, add .cache/ to .gitignore, make the plugin's enabled flag read an environment variable so local serves can skip it, and add an apt-get step for the Cairo, FreeType, libffi, libjpeg, libpng and zlib dev packages to both workflows before the install script. Install those packages in your sandbox, run the install script and mkdocs build --strict, count the generated cards, read the og:image and twitter:card tags in site/index.html, look at two cards, run the check script, and open a pull request with the 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 `mkdocs.yml`, `requirements.txt`, `.gitignore`, `docs/index.md`, `docs/quickstart.md`, `.github/workflows/test-suite.yml` and `.github/workflows/publish.yml`. Its description shows the `mkdocs build --strict` output, the number of cards generated against the number of pages in the nav, the `og:image` URL and `twitter:card` value read from the built index page, two of the cards as images, and the `scripts/check` result.

The `Test Suite` workflow runs on the pull request with the new apt step and the same build, and the cards are generated by `mkdocs build` from then on, so the next tag's `gh-deploy` publishes them with the site. No page content changes beyond the two descriptions, and the sponsor partial in `docs/overrides` is untouched.

Before merging, a reviewer looks at the cards and decides on the colours, the font and whether the logo should be the butterfly or a wordmark, checks the descriptions read well as a one-line summary on a shared link, and decides whether every page needs one or the site description is enough for the rest.

## Run it on every docs site without preview images

A team with several documentation sites sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request. Each run reads its own build: a site on Read the Docs gets the system packages in `.readthedocs.yaml` under `build.apt_packages` instead of a workflow step, one that already has a `plugins` list gets `social` appended, and one with `mkdocs-material` below 9 is told to upgrade first.

Once merged, every build regenerates the cards, so no further run is needed. A `webhook_url` on the key reports each `run.completed` with the pull request in `result`, and a `run.failed` names a site whose strict build did not pass with the plugin on, which usually means a page title the layout cannot fit.

## Why run it on Rush?

Turning the plugin on is one line; making it build everywhere is the work: the native libraries on the CI runner, the pinned Python packages, a cache directory kept out of git, a way for a developer without Cairo to serve the site, and descriptions that read well on a card. The agent does all of it in its own sandbox and shows the cards it produced, not a config it hopes renders.

The strict build, the card count, the meta tags and the images stay with the run and are pasted into the pull request, so the review is about how the cards look rather than whether the plugin works. Several sites can get cards at once, each with its own palette and logo.

## Frequently asked questions

### Why pin pillow and cairosvg instead of using the imaging extra?

The repository pins every tool in `requirements.txt` on purpose, as its own comment explains, so two pinned packages follow that rule. `mkdocs-material[imaging]` would install the same two without a pin.

### Will mkdocs serve still work on a laptop without Cairo?

Yes. The plugin's `enabled` key reads an environment variable, so a developer sets it to false and serves the site without cards. CI and the publish job leave it on, so the deployed site always has them.

### Does this change the search?

No. Adding a `plugins` list disables the default search unless `search` is listed, so it is listed first and behaves as before.

### How long does the build take now?

The plugin draws one image per page and caches it under `.cache/`, so a first build is slower and later builds only redraw changed pages. The pull request reports the timing it saw in the sandbox for this site rather than a guess.

## More MkDocs jobs

- [Add a Spell Check to MkDocs Docs in CI](https://getrush.ai/run/add-typo-check/mkdocs/)
- [Add Versioned Documentation to an MkDocs Site With mike](https://getrush.ai/run/add-versioned-docs/mkdocs/)
- [Migrate MkDocs API Docs From mkautodoc to mkdocstrings](https://getrush.ai/run/migrate-to-mkdocstrings/mkdocs/)

## The same job on other stacks

- [Add Social Cards to Sphinx Docs](https://getrush.ai/run/add-social-cards/sphinx/)
- [Add Social Cards to a VitePress Blog](https://getrush.ai/run/add-social-cards/vitepress/)
- [Add Social Cards to an Eleventy Blog](https://getrush.ai/run/add-social-cards/eleventy/)

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