All jobs

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

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

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

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

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading