All jobs

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

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

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

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

The same job on other stacks

Keep reading