All jobs

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

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

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

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

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading