Generate a PDF file for each MkDocs page, with the possibility of selecting individual pages for export
Project description
CM MkDocs Plugins - MkDocs Page to PDF
An MkDocs plugin to generate a PDF file for each MkDocs page using pyppeteer
(chrome headless) and add a download button.
This was forked from the great work done by https://github.com/brospars/mkdocs-page-pdf and changed to allow individual PDF export instead of excluding paths from export.
How to use
Install the package with pip:
pip install mkdocs-cm-page-to-pdf
Enable the plugin in your mkdocs.yml:
plugins:
# - ...
- pdfexport # should be last
Options
To set different options use the following syntax.
plugins:
# - ...
- pdfexport:
# Options here
disable
(bool): Disable pdf rendering useful to quickly disable it without removing the plugin config. Defaults toFalse
.disableOnServe
(bool): Disable pdf rendering when usingmkdocs serve
. Defaults toFalse
.
The following options are directly induced from pyppeteer options :
scale
(float): Scale of the webpage rendering, defaults to1.0
.displayHeaderFooter
(bool): Display header and footer. Defaults toFalse
.headerTemplate
(str): HTML template for the print header. Should be valid HTML markup with following classes.date
: formatted print datetitle
: document titleurl
: document locationpageNumber
: current page numbertotalPages
: total pages in the document
footerTemplate
(str): HTML template for the print footer. Should be valid HTML markup with the same classes asheaderTemplate
.printBackground
(bool): Print background graphics. Defaults toFalse
.landscape
(bool): Paper orientation. Defaults toFalse
.pageRanges
(string): Paper ranges to print, e.g., '1-5,8,11-13'. Defaults to empty string, which means all pages.format
(str): Paper format. Defaults toA4
.margin
(dict): Paper margins.top
(str): Top margin, accepts values labeled with units, defaults to20px
.right
(str): Right margin, accepts values labeled with units, defaults to20px
.bottom
(str): Bottom margin, accepts values labeled with units, defaults to20px
.left
(str): Left margin, accepts values labeled with units, defaults to20px
.
pageLoadOptions
(dict): Page load options (see this).timeout
(int): Maximum time in milliseconds, defaults to30000
.waitUntil
(str): When to consider navigation succeeded, defaults toload
.
exclude
(list) : List of glob pattern to exclude
Troubleshooting
Running in a docker container (ci/cd)
Depending on what image you are using you may encounter some issue running pyppeteer
: Browser closed unexpectedly
This is due to some missing shared librairies used by Chrome Headless.
Related issue : https://github.com/pyppeteer/pyppeteer/issues/194
See this article
and this guide
Slow build on serve
You can use disable
or disableOnServe
options to disable the pdf rendering (entirely or on serve) but you can also
use the mkdocs serve --dirtyreload
flag to only rebuild modified files on the fly.
Blank page at the end
Due to a chrome bug a blank page can appear at the end of the PDF you can remove it by addin the following to you extra.css :
body {
contain: strict;
}
Special thanks
This plugin was inspired by mkdocs-with-pdf
and mkdocs-pdf-export-plugin
but without using weasyprint
and instead pyppeteer
(chrome headless) to have a render
closer to what you have in your chrome browser.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_cm_page_to_pdf-0.1.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bfa9a7ca3026c85778d221bca3b78c3b46b36bfa35628fad19bd13b4a21ac3c8 |
|
MD5 | 9823bbbb86625b5eb670a29be04313c3 |
|
BLAKE2b-256 | 5cf659bbbc5e60ed943b2c79d20e7e0673b2f26014d52223b45d0acdf303328f |
Hashes for mkdocs_cm_page_to_pdf-0.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 58a4f91666ebba3367b5c59ceb9490b21ae3251edad2b524f5930b0a01310006 |
|
MD5 | 8d0e0979886ab76e922285e0ac85c546 |
|
BLAKE2b-256 | 7ad0169ca3ffb5c0f5ba9954130b67c2a840072ae890054f8af8f8f379762bba |