Generate a single PDF file from MkDocs repository
Project description
PDF Generate Plugin for MkDocs
This plugin will generate a PDF 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
Requirements
- This package requires MkDocs version 1.0 or higher (0.17 works as well)
- Python 3.4 or higher
- WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow the installation instructions for your platform carefully:
If you want to add a new theme, see adding support for new themes for more information.
How to use
Installation
-
Install the package with pip:
pip install mkdocs-with-pdf
-
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
#heading_shift: false
#toc_level: 3
#ordered_chapter_level: 2
#excludes_children:
# - 'release-notes/:upgrading'
# - 'release-notes/:changelog'
#
#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: usesite_author
in your projectmkdocs.yml
-
copyright
Set the author text.
default: usecopyright
in your projectmkdocs.yml
author
andcopyright
values are drawn in Cover, and you can use '@page' content.@page { @bottom-left { content: string(author); } @bottom-right { content: string(copyright); } }
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: usesite_name
in your projectmkdocs.yml
-
cover_subtitle
Set the subtitle text in cover page.
default:None
for Heading and TOC
-
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
to3
.
default:3
-
ordered_chapter_level
Set the level of heading number addition. This value is enabled in the range of from
1
to3
.
default:3
-
excludes_children
Set the page
id
ofnav
url. If theid
matches in this list, it will be excluded from the heading number addition and table of contents.
default:[]
... 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 tostdout
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.