MkDocs PDF Generate

An MkDocs plugin to generate individual PDF files from content pages.

The pdf-generate plugin will generate separate PDF files for each markdown page in your MkDocs repository using WeasyPrint. The exported documents support many advanced features such as table of contents, customisable cover page , support for CSS paged media module CSS paged media module , and using MkDocs page metadata to generate cover page.

Requirements

1. This package requires MkDocs version 1.4.2 or higher (MkDocs <1.4.2 might work as well)
2. Python 3.8 or higher
3. WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow the installation instructions for your platform carefully:
   • Linux
   • MacOS
   • Windows
4. Explicit support for your mkdocs theme is probably required. As of now, the only supported theme is mkdocs-material. A generic version will just generate the PDF files and put the download link into a <link> tag.

Installation

Install the package with pip:

Linux & MacOS

python -m pip install -e "git+https://github.com/iSOLveIT/mkdocs-pdf-generate/#egg=mkdocs-pdf-generate"

Windows

C:> python -m pip install -e "git+https://github.com/iSOLveIT/mkdocs-pdf-generate/#egg=mkdocs-pdf-generate"

Install from source repository in a virtual environment:

cd [YOUR_PROJECT_DIRECTORY]
git clone https://github.com/iSOLveIT/mkdocs-pdf-generate
cd mkdocs-pdf-generate
pip install -e .

Enable the plugin in your mkdocs.yml:

plugins:
    - search
    - pdf-generate

Note: If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

More information about plugins in the MkDocs documentation.

Testing

When building your repository with mkdocs build, you should now see the following message at the end of your build output:

Converting 17 files to PDF took 15.6s

In your site_dir you should now have a PDF file for every markdown page.

Options

For more information on options, visit the plugin's documentation.

Contributing

From reporting a bug to submitting a pull request: every contribution is appreciated and welcome. Report bugs, ask questions and request features using GitHub issues.

If you want to contribute to the code of this project, please read the Contribution Guidelines.

Special thanks

• Terry Zhao the author of the MkDocs PDF Export Plugin the source of our inspiration. We've used some of his code in this project.