MkDocs with PDF

0.9.3 verified Mon Apr 27 auth: no python

A MkDocs plugin that generates a single PDF file from your MkDocs documentation repository. Version 0.9.3 is the latest stable release (requires Python >=3.6). The project is actively maintained, with periodic releases fixing bugs and adding features.

pip install mkdocs-with-pdf

Common errors

error OSError: cannot load library 'libcairo.so.2' ↓

cause Missing system dependency for WeasyPrint.

fix

Install cairo: on Ubuntu: sudo apt-get install libcairo2-dev; on macOS: brew install cairo; on Windows: use GTK+ installer.

error ModuleNotFoundError: No module named 'mkdocs_with_pdf' ↓

cause The package is not installed or not in the current environment.

fix

Run 'pip install mkdocs-with-pdf' to install the plugin.

error AttributeError: 'NoneType' object has no attribute 'name' ↓

cause Occurs when the 'exclude_pages' option is misconfigured (e.g., using old syntax).

fix

Upgrade to v0.9.3 and ensure 'exclude_pages' uses the new pattern format (list of globs or regexes).

Warnings

gotcha WeasyPrint requires external system dependencies (e.g., cairo, Pango). Install them according to your OS or the PDF generation will fail silently. ↓

fix Follow the WeasyPrint installation docs: https://doc.courtbouillon.org/weasyprint/stable/first_steps.html

breaking Python 3.5 support was dropped in v0.9.0. If you use Python 3.5, stick with v0.8.3. ↓

fix Upgrade Python to 3.6+ or pin version to 0.8.3.

gotcha The plugin does not work with the 'material' theme's navigation tabs when 'tabs' is set to true. You may need a custom theme or workaround. ↓

fix Set theme.features.tabs to false or switch to a different theme.

deprecated The 'exclude_pages' option changed its behavior in v0.9.0. Previously it excluded pages by relative path, now it uses a pattern or regex. ↓

fix Update your mkdocs.yml to use the new exclude_pages pattern (e.g., '*/api/*').

gotcha If your page titles contain numbers only (e.g., '404'), the plugin may crash. This was fixed in v0.9.3. ↓

fix Upgrade to v0.9.3 or ensure page titles include letters.

Imports

MkdocsWithPdfPlugin

from mkdocs_with_pdf import MkdocsWithPdfPlugin

Quickstart

Enable the plugin in your mkdocs.yml and build the site to generate a PDF.

# Ensure mkdocs.yml has the plugin enabled:
# plugins:
#   - with-pdf

# Then build your docs:
mkdocs build