mkdocs-with-pdf 0.7.2

Generate a single PDF file from MkDocs repository

PDF Generate Plugin for MkDocs

---

This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export Plugin.

Features

• Cover and Table of Contents integrated in the PDF
• Automatically numbers on heading(h1-h3).
• Shift down sub-page headings level.
• using WeasyPrint.

Samples

• PDF of 'MkDocs' docs
• PDF of 'Material for MkDocs' docs

Requirements

1. This package requires MkDocs version 1.0 or higher (0.17 works as well)
2. Python 3.5 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

How to use

Installation

1. Install the package with pip:

   pip install mkdocs-with-pdf
   

2. Enable the plugin in your mkdocs.yml:

   plugins:
       - with-pdf
   

   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 10 articles to PDF took 7.1s

Configuration

You may customize the plugin by passing options in mkdocs.yml:

plugins:
    - with-pdf:
        #author: WHO
        #copyright: ANY TEXT
        #
        #cover: false
        #cover_title: TITLE TEXT
        #cover_subtitle: SUBTITLE TEXT
        #
        #toc_title: TOC TITLE TEXT
        #heading_shift: false
        #toc_level: 3
        #ordered_chapter_level: 2
        #excludes_children:
        #    - 'release-notes/:upgrading'
        #    - 'release-notes/:changelog'
        #
        #exclude_pages:
        #    - 'bugs/'
        #    - 'appendix/contribute/'
        #convert_iframe:
        #    - src: IFRAME SRC
        #      img: POSTER IMAGE URL
        #      text: ALTERNATE TEXT
        #    - src: ...
        #two_columns_level: 3
        #
        #render_js: true
        #headless_chrome_path: headless-chromium
        #
        #output_path: any-place/document.pdf
        #enabled_if_env: ENABLE_PDF_EXPORT
        #
        #debug_html: true
        #verbose: true

Options

for Properties

• author

  Set the author text.
  default: use site_author in your project mkdocs.yml

• copyright

  Set the author text.
  default: use copyright in your project mkdocs.yml

author and copyright values are drawn in Cover, and you can use '@page' content.

@page {
  @bottom-left {
    content: string(author) !important;
  }
  @bottom-right {
    content: string(copyright) !important;
  }
}

for Cover

• cover

  Set the value to false if you don't need a cover page.
  default: true

• cover_title

  Set the title text in cover page.
  default: use site_name in your project mkdocs.yml

• cover_subtitle

  Set the subtitle text in cover page.
  default: None

for Heading and TOC

• toc_title

  Set the title text of Table of Content.
  default: Table of Content
  since: v0.4.0

• heading_shift

  Set this value to false, disable shift heading in child page.
  default: true

  In this flags enable, heading move down one level in child page.

• toc_level

  Set the level of Table of Content. This value is enabled in the range of from 1 to 3.
  default: 3

• ordered_chapter_level

  Set the level of heading number addition. This value is enabled in the range of from 1 to 3.
  default: 3

• excludes_children

  Set the page id of nav url. If the id matches in this list, it will be excluded from the heading number addition and table of contents.
  default: []

for Page

• exclude_pages

  Set the page id of nav url. If the id matches in this list, it will be excluded page contents.
  default: []
  since: v0.3.0

• convert_iframe

  List of iframe to a conversions. Every iframe that matches a src in this list will be replace to a contains each img and/or text. it's using for such as embedded VIDEO.
  default: []
  since: v0.6.0

  @see Sample of MkDocs Material

• two_columns_level (Experimental)

  Set the heading level of Two Column Layout. Currently only 0(disable) or 3 is valid for this value. So slow processing, but a little nice.

  default: 0
  since: v0.7.0

  @see Sample of MkDocs Material

Renderer for JavaScript

• render_js

  Set the value to true if you're using 'MathJax', 'Twemoji' or any more.
  Require "Chrome" which has "headless" mode.

  default: false
  since: v0.7.0

• headless_chrome_path

  Set the "Headless Chrome" program path.
  If render_js is false, this value will be ignored.

  default: chromium-browser

Check on your system:

$ <PROGRAM_PATH> --headless \
   --disable-gpu \
   --dump-dom \
   <ANY_SITE_URL(eg. 'https://google.com')>

... and more

• output_path

  This option allows you to use a different destination for the PDF file.
  default: pdf/document.pdf

• enabled_if_env

  Setting this option will enable the build only if there is an environment variable set to 1. This is useful to disable building the PDF files during development, since it can take a long time to export all files.
  default: None

• debug_html

  Setting this to true will out HTML to stdout on build time.
  default: false

  You can try this:

  mkdocs build > for_pdf_print.html
  

• verbose

  Setting this to true will show all WeasyPrint debug messages during the build.
  default: false

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 to

• 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.