Setting up PDF documents
Prerequisites
Under-the-hood, this library depends on a web browser controlled by Playwright to generate PDF documents.
At the time of writing, Playwright supports the following operating systems:
- Python 3.8 or higher
- Windows 10+, Windows Server 2016+ or Windows Subsystem for Linux (WSL)
- macOS 12 Monterey or MacOS 13 Ventura
- Debian 11, Debian 12, Ubuntu 20.04 or Ubuntu 22.04
Your operating system is not supported?
You can still use Docker to build your documentation from any operating system.
Feel free to check out the Dockerfile used by this documentation.
To install the browser and its required dependencies, run:
playwright install --with-deps
Configuration
First of all, you'll need to register the exporter-pdf
plugin (after the exporter
one) to your configuration:
plugins:
- exporter
- exporter-pdf
You can find the configuration reference here.
Why multiple plugins?
MkDocs Exporter comes as various plugins in a single package.
This architecture reduces code duplication and maintains a generic base that can be used to export your pages to formats other than PDF (although this is currently the only format supported).
To sum things up, the exporter
plugin should always be registered first as it provides a common ground for other plugins to rely on.
Usage
Toggling documents generation
Document generation can be enabled or disabled at any time. This feature is particularly useful during your development processes: when you don't want to slow down your iterations because of document generation.
plugins:
- exporter
- exporter-pdf:
enabled: ![MKDOCS_EXPORTER_ENABLED, true]
With this configuration, the MKDOCS_EXPORTER_ENABLED
environment variable can be used as a switch for the generation process.
Setting up cover pages
Cover pages can give your PDF documents a professional quality.
Here's how cover pages are set up for this documentation.
Power! Unlimited Power!
The following examples use the macros
plugin for extra powerful pages.
plugins:
- exporter
- exporter-pdf:
stylesheets:
- resources/stylesheets/pdf.scss
covers:
front: resources/templates/covers/front.html.j2
back: resources/templates/covers/back.html.j2
[...]
See the full content of this file here.
<div class="front-cover">
<img src="/assets/images/background.png">
<section>
<div class="brand">{{ config.site_name }}</div>
<div class="title">{{ page.title }}</div>
</section>
</div>
[...]
See the full content of this file here.
<div class="back-cover">
<section>
<div class="title">{{ config.site_name }}</div>
</section>
</div>
[...]
See the full content of this file here.
@page {
size: A4;
margin: 1.20cm;
}
[...]
See the full content of this file here.
Increasing concurrency
PDF are, by default, generated concurrently which greatly reduces the overall build time.
You may want to override the default value of 4, depending on your hardware.
plugins:
- exporter-pdf:
concurrency: 16
With this configuration, up to 16 PDF documents will be generated concurrently.
As you've guessed, a value of 1 will force PDF documents to be built sequentially.
Excluding some pages
You may want to prevent some pages from generating a PDF document.
To do so, you can use the pdf
meta tag on your pages:
---
pdf: false
---
# Lorem ipsum dolor sit amet
[...]
If you exclude more pages than you include, you may want to explicitly define the pages for which PDF documents should be generated.
This behaviour is called the explicit
mode, it can be enabled in your configuration file:
plugins:
- exporter-pdf:
explicit: true
With this option, only pages with a truthy pdf
meta tag will have their corresponding PDF document generated.
---
pdf: true
---
# Lorem ipsum dolor sit amet
[...]