# Add PDF Export to an mdBook Book

Yes. An agent adds a CI job that renders your mdBook book to PDF with mdbook-pdf, keeps the existing build and link check untouched, and opens a PR with the file.

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

## What the agent does

The agent reads the book and its build before adding a backend. In a book like rust-lang/nomicon, `book.toml` has one renderer, `[output.html]`, with `additional-css = ["theme/nomicon.css"]`, a `git-repository-url`, a long `[output.html.redirect]` table that maps the old flat chapter paths to the `vec/` and `arc-mutex/` directories, and `[rust] edition = "2024"`. There are forty-eight source files under `src/`, `SUMMARY.md` nests them three levels deep, and `theme/nomicon.css` styles the `<div class="warning">` blocks that `intro.md` and other chapters use, with separate colours for the `light`, `rust`, `coal`, `navy` and `ayu` themes. The CI workflow, `.github/workflows/main.yml`, pins `MDBOOK_VERSION: 0.5.1`, downloads that release's `x86_64-unknown-linux-gnu` tarball into a `bin/` directory it adds to `PATH`, installs a nightly Rust toolchain, runs `mdbook test` and then the `linkcheck.sh` script from rust-lang/rust, and gates merges on a `success` job. Nothing produces a printable copy beyond the print icon mdBook's HTML renderer adds by default.

The backend is mdbook-pdf, a Rust crate that renders the book's `print.html` with a headless Chromium through the DevTools `printToPDF` call; the README requires `[output.html.print]` to stay enabled, which it is by default, and says the broken-link problem in `print.html` was fixed in mdBook 0.5.0 and later, which this book's 0.5.1 pin satisfies. The obvious change, a second `[output.pdf]` table in `book.toml`, has a side effect the agent finds by reading `linkcheck.sh`: that script runs `mdbook build` itself and copies the whole `book/` directory as the book's HTML, and mdBook with two renderers writes `book/html/` and `book/pdf/` instead of `book/` alone, so the link check would stop finding the chapters. mdBook's configuration documentation gives the way out: any `MDBOOK_*` environment variable overrides a key, its value is parsed as JSON first, and `__` separates nested keys, so a job can set `MDBOOK_OUTPUT__PDF` to a JSON object and add the renderer for that build only. `book.toml` stays as it is, local `mdbook build` and `mdbook serve` are unchanged, and the test and link-check steps never see a second renderer.

The new job, `pdf`, runs beside `test` and feeds the `success` gate through `needs`. It downloads the same mdBook tarball, then `mdbook-pdf-v0.1.13-x86_64-unknown-linux-gnu` from the crate's GitHub release, the current one, into `bin/`, marks it executable, and runs `mdbook build` with `MDBOOK_OUTPUT__PDF` set to the options the crate's `test_doc/book.toml` documents, chosen for a long technical book: `generate-document-outline` true, so the PDF gets bookmarks from the chapter headings; `display-header-footer` true with a footer template that prints `pageNumber` of `totalPages`; `print-background` true, so the warning boxes keep their fill; and `theme` set to `light`, the first colour set in `nomicon.css`. `static_site_url` is left out because the Nomicon's outbound links are absolute. The job uploads `book/pdf/output.pdf` with `actions/upload-artifact`, so every pull request carries a downloadable copy. GitHub's Ubuntu runner has a Chromium-based browser installed, which is how the backend finds one with no configuration; the README adds that where it does not, `browser-binary-path` names the binary, and the job comment says so. The same options go into the README's build section as a one-line local command, for an author who wants the PDF on their own machine.

Before the pull request the agent runs the job's commands in its sandbox: it installs mdBook 0.5.1 and mdbook-pdf 0.1.13 the way the workflow does, sets `browser-binary-path` in the JSON to the browser in the sandbox if the backend does not find one on its own, runs the build, and opens `book/pdf/output.pdf` in that browser. It checks the outline lists the chapters in `SUMMARY.md` order, that a `warning` block in the introduction kept its border and background, that code blocks did not lose their highlighting, and that a chapter which cross-references another, such as the `vec` chapters, links to a place in the same file. It then runs `mdbook build` without the variable and confirms `book/` still has the HTML at its root, which is what `linkcheck.sh` needs. It reads the file size and the page count from the viewer and puts both in the pull request, with a screenshot of the outline from the run's record.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add PDF export to this mdBook book with the mdbook-pdf backend without changing how the existing build, test and link check run. Read book.toml, the theme directory, src/SUMMARY.md, .github/workflows and any link-check script the workflow downloads first. If a second renderer in book.toml would move the HTML output into a subdirectory that the link check does not expect, keep book.toml unchanged and add the pdf renderer only in a new CI job through the MDBOOK_OUTPUT__PDF environment variable with a JSON value. In that job install the same mdbook version the workflow pins, download the mdbook-pdf release binary for x86_64 Linux at the current crate version, run mdbook build with generate-document-outline, display-header-footer with a page-number footer, print-background and a theme matching the book's light styles, and upload book/pdf/output.pdf as an artifact; add the job to the success gate. Document the same one-line local command in the README. In the sandbox, install the same versions, set browser-binary-path if the backend cannot find the browser, build, open the PDF in the browser and check the outline, a warning block, code highlighting and an internal cross-reference; then build without the variable and confirm the HTML output location is unchanged. Open a pull request with the commands, the PDF's page count and size, and a screenshot of the outline.",
  "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 `.github/workflows/main.yml` and `README.md` and nothing else; `book.toml`, the sources under `src/`, `theme/nomicon.css` and the redirect table are untouched. Its description quotes the build log showing both renderers running in the new job, names the mdBook and mdbook-pdf versions it pinned, gives the PDF's page count and size as read from the viewer, explains why the renderer lives in an environment variable rather than `book.toml`, and includes the outline screenshot. The workflow run on the pull request itself produces the first PDF artifact a reviewer can download without building anything.

A reviewer opens that artifact and reads a chapter or two: page breaks between chapters, which `[output.html.print]` inserts by default, the footer numbering, and whether the `light` theme is the one they want in print. Two decisions stay with them: whether to publish the PDF somewhere readers can find it, which the pull request leaves out because the book's hosting is not in this repository, and whether to move the options into `book.toml` as `[output.pdf]` with `optional = true` once the link check is adjusted, which the pull request describes as the follow-up.

## Run it on every release of the book

A project that tags releases of its documentation sends this body once from its own server when the book's repository is set up, with a `request_id` that is a UUID v5 of the repository's full name so a retried call returns the same run. Afterwards the job the agent added produces the PDF on every push without an agent; for a second repository with its own book, the same body with that repository in `resources` fits its `book.toml` and workflow, because the agent reads them rather than assuming the same layout.

The key's `webhook_url` reports each run with the pull request URL in `result`, so a script that sent several requests collects the pull requests without polling.

## Why run it on Rush?

A PDF backend is easy to declare and hard to get right: it needs a browser the backend can find, a print stylesheet that keeps the book's own CSS, link fixes that only recent mdBook versions provide, and a CI step that installs the exact binary. It can also break what is already there, as it would here by moving the HTML output out from under a link checker. The agent reads the pinned mdBook version and the scripts the workflow downloads, installs the matching backend in its own sandbox, renders the book with the sandbox's browser, opens the result and keeps the commands, the log and the screenshots in the run's record, so the pull request arrives with a PDF that has been looked at and a build that still passes.

The book's own choices steer the configuration: a `warning` class with per-theme colours means `print-background` and a named `theme`; a three-level `SUMMARY.md` means the document outline is worth turning on; a workflow that already downloads mdBook from a release tarball means the backend is installed the same way rather than through a `cargo install` that would add minutes to every run. A different book gets a different set of options, read from its files.

## Frequently asked questions

### Does this need Chrome in CI?

It needs a Chromium-based browser, which GitHub's Ubuntu runners already have, so the job adds no browser install. On a self-hosted runner without one, add `browser-binary-path` to the JSON in `MDBOOK_OUTPUT__PDF` or install Chromium, and the pull request says where that goes.

### Why is the renderer not in book.toml?

Because the book's link check runs `mdbook build` itself and copies `book/` as the HTML, and a second renderer in `book.toml` makes mdBook write `book/html/` and `book/pdf/` instead. Setting `MDBOOK_OUTPUT__PDF` in the one job that wants the PDF adds the renderer there only; mdBook documents that environment variables override configuration and are parsed as JSON first. A book without that constraint can put the same keys under `[output.pdf]` with `optional = true`, and the pull request shows that form.

### Why not cargo install mdbook-pdf in the workflow?

The crate publishes prebuilt binaries for each release, and the book's workflow already installs mdBook from a release tarball rather than compiling it. Downloading the matching binary keeps the step to seconds and pins a version the same way `MDBOOK_VERSION` does; `cargo install mdbook-pdf` works too and the pull request names it as the alternative.

### Will internal links work inside the PDF?

Links between chapters resolve to anchors within `print.html`, which is what mdbook-pdf renders, and the crate's README notes this was fixed in mdBook 0.5.0 and later; this book pins 0.5.1. Relative links that leave the book need `static_site_url` so they point at the hosted site, and the pull request sets it if the agent finds any.

### Can the PDF have a table of contents with bookmarks?

Yes. `generate-document-outline` set to true asks Chromium to build the outline from the headings, which viewers show as bookmarks. The crate also offers a separate `mdbook-pdf-outline` backend written in Python for a different outline style, which the pull request mentions but does not add.

## More mdBook jobs

- [Add Redirects for Moved Pages to an mdBook](https://getrush.ai/run/add-redirects/mdbook/)
- [Add a Sitemap to an mdBook Site](https://getrush.ai/run/add-sitemap/mdbook/)
- [Add a Table of Contents to mdBook Chapters](https://getrush.ai/run/add-table-of-contents/mdbook/)

## The same job on other stacks

- [Add PDF Export to a MkDocs Site](https://getrush.ai/run/add-pdf-export/mkdocs/)
- [Add PDF Export to Sphinx Docs](https://getrush.ai/run/add-pdf-export/sphinx/)

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