# Add PDF Export to a MkDocs Site

Yes. An agent adds a print page covering your whole MkDocs site, a PDF built from it in CI and a download link, checks the build and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pdf-export/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 site is built before adding a page to it. In a project like encode/httpx, `mkdocs.yml` uses the `material` theme with a `custom_dir` of `docs/overrides`, a light and dark palette with a toggle, a `nav` of five groups, Introduction, QuickStart, Advanced with ten pages, Guides, API Reference and Community, `markdown_extensions` of `admonition`, `codehilite` and `mkautodoc`, and `extra_css` pointing at `css/custom.css`. There is no `plugins` key, which means the `search` plugin is on by default and will stop being the moment one is added. `requirements.txt` pins `mkdocs==1.6.1`, `mkdocs-material==9.6.18` and `mkautodoc==0.2.0`. `scripts/build` runs `python -m build`, `twine check` and `mkdocs build`, `.github/workflows/test-suite.yml` runs that script on Python 3.9 through 3.13 for every pull request, `scripts/docs` runs `mkdocs serve`, and `scripts/publish` deploys with `mkdocs gh-deploy --force` on a tag. `docs/overrides/partials/nav.html` replaces the theme's primary navigation partial, which the agent reads to be sure a new nav entry renders through it.

The print page comes from `mkdocs-print-site-plugin`, which assembles every page in `nav` order into one HTML page at `/print_page/`, with a table of contents, section numbers and print styles, so the browser's print dialog produces a PDF of the whole site. The agent adds the plugin to `requirements.txt`, pinned to the current 2.x release, whose own requirement is `mkdocs<=1.6.1`, so it fits the pin already there, and adds a `plugins` list to `mkdocs.yml` with `search` first and `print-site` last, the order the plugin's documentation asks for so other plugins' changes to the navigation are included. The block sets `add_to_navigation: true` with a `print_page_title` of `Print and PDF`, keeps `add_table_of_contents` at its default, sets `enumerate_headings: false` so headings read as they do on the site, `add_cover_page: true` with a `cover_page_template` under `docs/overrides/` that names the project and the version from `httpx/__version__.py`, and `exclude` for `code_of_conduct.md` and `contributing.md`, which belong on the site but not in a manual. `path_to_pdf` points at the file the workflow below produces, which puts a download link on every page.

The PDF itself is built in CI rather than committed. The agent adds a `docs-pdf` job to `.github/workflows/test-suite.yml` that runs `mkdocs build`, installs Chromium through Playwright's package, prints `site/print_page/index.html` to `site/httpx.pdf` with headless Chromium, and uploads it with `actions/upload-artifact`, so every pull request has a PDF to open from its checks. `scripts/publish` gets the same two lines before `gh-deploy` so the file deploys with the site at the path `path_to_pdf` names. The job uses the pinned requirements, so the versions in CI match the ones a developer runs locally.

Then the agent checks the result the way the project does. It runs `scripts/build` in its sandbox, then `mkdocs build --strict` to surface any warning the plugin raises about the nav, and looks at `site/print_page/index.html` for the cover, the contents and the `mkautodoc` sections from `api.md`, which render through the same Markdown pipeline and so appear in the print page with their signatures. It opens the page in its browser in both palettes, prints it to PDF with the same Chromium command the workflow uses, opens the PDF to read the first pages and the contents, and keeps the screenshots in the run's record.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a print page and a PDF export to this MkDocs site. Read mkdocs.yml, requirements.txt, scripts/build, scripts/docs, scripts/publish, .github/workflows/test-suite.yml and docs/overrides first. Add mkdocs-print-site-plugin to requirements.txt pinned to the current release, add a plugins list to mkdocs.yml with search first and print-site last, with add_to_navigation on, a print page title, enumerate_headings off, a cover page template under docs/overrides naming the project and its version, code_of_conduct.md and contributing.md excluded, and path_to_pdf pointing at a PDF deployed with the site. Add a CI job that builds the site, prints site/print_page/index.html to a PDF with headless Chromium and uploads it as an artifact, and add the same PDF step to scripts/publish before gh-deploy. Run scripts/build and mkdocs build --strict, open the print page in the browser in both palettes, produce the PDF with the same command, and open a pull request quoting 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`, `scripts/publish` and `.github/workflows/test-suite.yml`, and adds the cover page template under `docs/overrides/`. Its description quotes the `scripts/build` and `mkdocs build --strict` output, names the pages the print page contains in order and the two it excludes, and shows the print page in both palettes and the first page of the PDF from the run's record. The PDF itself is attached to the workflow run on the pull request, not to the repository.

A reviewer opens the artifact, reads the contents page against the site's `nav`, and checks the two decisions that are matters of taste: whether headings should be numbered and which pages belong in a manual. The plugin block is a dozen lines, and the workflow job runs the same commands the reviewer can run locally with `mkdocs build` and a browser.

## Run it on every documentation site repository

A team with several MkDocs sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming one repository in `resources` with 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 `mkdocs.yml`: a site that already lists plugins gets `print-site` appended rather than a new list, a site on an older MkDocs pin gets the plugin release that supports it, and a site with no CI gets the PDF step in whatever script publishes it.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a page to nav, confirm it is included in the print page or listed in the plugin's exclude, and post a review" keeps the manual complete as the site grows. The trigger adds the pull request after the prompt and fills in nothing else.

## Why run it on Rush?

A print page is configuration until someone opens it, and the mistakes are in what it includes, what it numbers and whether the build still passes in strict mode. The agent builds the site with the project's own script in its own sandbox, opens the page in a browser in both palettes, prints it to a PDF with the same command the workflow runs, and keeps the commands, output and screenshots in the run's record.

The version pins are the other half: a plugin release that wants a newer MkDocs than the site pins breaks the build for every contributor. The agent reads `requirements.txt` and the plugin's own requirement and chooses a release that satisfies both, and the pull request says which.

## Frequently asked questions

### Why not commit the PDF?

A PDF changes with every docs edit and bloats the repository's history. The workflow builds it on every pull request as an artifact and `scripts/publish` deploys it beside the site, so the download link on each page always points at the PDF of the published version.

### Will adding plugins turn off search?

It would if `search` were left out, because MkDocs enables it by default only when there is no `plugins` key. The agent lists `search` first and `print-site` last, so search keeps working and the print page sees the final navigation.

### Do the API reference sections render in the print page?

Yes. `mkautodoc` runs as a Markdown extension, so the `::: httpx.Client` blocks in `api.md` render in the print page the same way they do on the site, with their docstrings and member lists. The agent checks the print page for them before opening the pull request.

### Can some pages be left out?

Yes. The plugin's `exclude` option takes page paths and glob patterns, and the pull request excludes the code of conduct and the contributing guide. Add any page that belongs on the site but not in a manual.

### Does this need WeasyPrint or LaTeX?

No. The print page is plain HTML with print styles, and the PDF comes from Chromium's print engine, which the workflow installs through Playwright's package. Nothing in the Python environment changes beyond the one plugin.

## More MkDocs jobs

- [Add Redirects for Moved Pages to a MkDocs Site](https://getrush.ai/run/add-redirects/mkdocs/)
- [Add Social Preview Cards to a MkDocs Material Site](https://getrush.ai/run/add-social-cards/mkdocs/)
- [Add a Spell Check to MkDocs Docs in CI](https://getrush.ai/run/add-typo-check/mkdocs/)

## The same job on other stacks

- [Add PDF Export to Sphinx Docs](https://getrush.ai/run/add-pdf-export/sphinx/)
- [Add PDF Export to an mdBook Book](https://getrush.ai/run/add-pdf-export/mdbook/)

## More jobs like this: Hand off a long task

- [Add PDF Upload to a Streamlit File Q&A App](https://getrush.ai/run/add-pdf-support/streamlit/)

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