Skip to content

An Mkdocs plugin to download documentation pages as pdf.

License

Notifications You must be signed in to change notification settings

brospars/mkdocs-page-pdf

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

33 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

How to use

Install the package with pip:

pip install mkdocs-page-pdf

Enable the plugin in your mkdocs.yml:

plugins:
  # - ...
    - page-to-pdf # should be last

Options

To set different options use the following syntax.

plugins:
  # - ...
    - page-to-pdf :
        # Options here
  • disable (bool): Disable pdf rendering useful to quickly disable it without removing the plugin config. Defaults to False.
  • disableOnServe (bool): Disable pdf rendering when using mkdocs serve. Defaults to False.

The following options are directly induced from pyppeteer options :

  • scale (float): Scale of the webpage rendering, defaults to 1.0.
  • displayHeaderFooter (bool): Display header and footer. Defaults to False.
  • headerTemplate (str): HTML template for the print header. Should be valid HTML markup with following classes.
    • date: formatted print date
    • title: document title
    • url: document location
    • pageNumber: current page number
    • totalPages: total pages in the document
  • footerTemplate (str): HTML template for the print footer. Should be valid HTML markup with the same classes as headerTemplate.
  • printBackground (bool): Print background graphics. Defaults toFalse.
  • landscape (bool): Paper orientation. Defaults to False.
  • 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 to A4.
  • margin (dict): Paper margins.
    • top (str): Top margin, accepts values labeled with units, defaults to 20px.
    • right (str): Right margin, accepts values labeled with units, defaults to 20px.
    • bottom (str): Bottom margin, accepts values labeled with units, defaults to 20px.
    • left (str): Left margin, accepts values labeled with units, defaults to 20px.
  • pageLoadOptions (dict): Page load options (see this).
    • timeout (int): Maximum time in milliseconds, defaults to 30000.
    • waitUntil (str): When to consider navigation succeeded, defaults to load.
  • 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 : pyppeteer/pyppeteer#194
See this article and this guide
Ready-to-use docker image : https://github.com/brospars/docker-mkdocs

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.

About

An Mkdocs plugin to download documentation pages as pdf.

Resources

License

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published

Languages