# Important Notice
This is a private fork of https://github.com/domWalters/mkdocs-to-pdf which hasn't yet published to PyPI. The domWalters' fork is a fork of the original https://github.com/orzih/mkdocs-with-pdf which seems to be abandoned.
I created this fork to be able to use some fixes. You can use it if you want, but I recommend using the original one unless you know what you are doing. I don't guarantee that I will maintain this fork.
To install this fork, you can use the following command:
```bash
pip install tlaguz.mkdocs-to-pdf
```
# PDF Generate Plugin for MkDocs
[](https://pypi.org/project/mkdocs-with-pdf)
[](https://pypi.org/project/mkdocs-with-pdf)
---
This plugin will generate a single PDF file from your MkDocs repository.
This plugin is inspired by [MkDocs PDF Export Plugin][mkdocs-pdf-export-plugin].
## Features
* Cover and Table of Contents integrated in the PDF
* Automatically numbers on heading (h1-h6).
* Shift down sub-page headings level.
* using [WeasyPrint][weasyprint].
## Samples
* [PDF of _'MkDocs' docs_][sample_mkdocs]
* [PDF of _'Material for MkDocs' docs_][sample_mkdocs-material]
[sample_mkdocs]: https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs/README.md
[sample_mkdocs-material]: https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/README.md
## Requirements
1. This package requires MkDocs version 1.0 or higher (0.17 works as well)
1. Python 3.6 or higher
1. WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow the installation instructions for your platform carefully:
* [Linux][weasyprint-linux]
* [MacOS][weasyprint-macos]
* [Windows][weasyprint-windows]
## How to use
### Installation
1. Install the package with pip:
```bash
pip install mkdocs-with-pdf
```
2. Enable the plugin in your `mkdocs.yml`:
```yaml
plugins:
- with-pdf
```
More information about plugins in the [MkDocs documentation][mkdocs-plugins].
#### 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`:
```yaml
plugins:
- with-pdf:
#author: WHO
#copyright: ANY TEXT
#
#cover: false
#back_cover: true
#cover_title: TITLE TEXT
#cover_subtitle: SUBTITLE TEXT
#custom_template_path: TEMPLATES PATH
#
#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
#show_anchors: 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.
>
> ```css "e.g."
> @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`
* `back_cover`
Set the value to `true` if you need a back cover page.
**default**: `false`
_**since**: `v0.8.0`_
You would be better to install the `qrcode` package:
```sh
pip install qrcode
```
* `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`
* `cover_logo`
Set the logo image in cover page. This value is URL or simply specify the relative path to the docs directory.
**default**: `None`
_**since**: `v0.8.0`_
##### 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 `6`.
**default**: `3`
* `ordered_chapter_level`
Set the level of heading number addition. This value is enabled in the range of from `1` to `6`.
**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_](https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/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_](https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/)
##### Renderer for JavaScript
* `render_js`
Set the value to `true` if you're using '[MathJax](https://www.mathjax.org/)', '[Twemoji](https://twemoji.twitter.com/)' 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')>
> ```
* `relaxedjs_path`
Set the value to execute command of relaxed if you're using e.g. '[Mermaid](https://mermaid-js.github.io) diagrams and Headless Chrome is not working for you.
Require "ReLaXed" Javascript PDF renderer to be installed on your system. See: '[ReLaXed](https://github.com/RelaxedJS/ReLaXed)'.
Please use 'theme_handler_path' option to specify custom JS sources and CSS Stylesheets which covers your needs. E.g. for Material
theme it would be **material.py**. See: **mkdocs-with-pdf/mkdocs_with_pdf/themes/material.py** for implementation details.
**default**: `None`
_**since**: `v0.7.0`_
> Install on your system:
> ```
> $ npm i -g relaxedjs
> $ relaxed --version
> ```
##### ... and more
* `output_path`
This option allows you to use a different destination for the PDF file.
**default**: `pdf/document.pdf`
* `custom_template_path`
The path where your custom `cover.html` and/or `styles.scss` are located.
**default**: `templates`
_**since**: `v0.8.0`_
* `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`
PDF generation can take significantly longer than HTML generation which can slow down mkdocs's built-in dev-server.
Adding `enabled_if_env: ENABLE_PDF_EXPORT` under `- with-pdf:` disables PDF generation during development. Run the dev-server normally:
```sh
$ mkdocs serve
INFO - Browser Connected: http://127.0.0.1:8000/
INFO - Running task: builder (delay: None)
INFO - Building documentation...
WARNING - without generate PDF(set environment variable ENABLE_PDF_EXPORT to 1 to enable)
... 2 seconds later ...
INFO - Reload 1 waiters: /.../index.md
```
and to build files to deploy specify `ENABLE_PDF_EXPORT=1` at the command line:
```sh
$ ENABLE_PDF_EXPORT=1 mkdocs build
...
INFO - Converting 10 articles to PDF took 7.1s
INFO - Documentation built in 8.29 seconds
```
* `debug_html`
Setting this to `true` will out HTML to `stdout` on build time.
**default**: `false`
You can try this:
```bash
mkdocs build > for_pdf_print.html
```
...and browse output with Google Chrome. [Chrome DevTools Into Print Preview Mode](https://developers.google.com/web/tools/chrome-devtools/css/print-preview) will you help.
Note: WeasyPrint and Google Chrome are not fully compatible.
* `show_anchors`
Setting this to `true` will list out of anchor points provided during the build as info message.
**default**: `false`
_**since**: `v0.7.4`_
* `verbose`
Setting this to `true` will show all WeasyPrint debug messages during the build.
**default**: `false`
## Custom cover page and document style
It is possible to create a custom cover page for the document.
You can also add a custom style sheet to modify the whole document.
To do so, add a `templates` folder at the root level of your `mkdocs` project and place a `cover.html` and/or a `styles.scss` inside.
Alternatively, you can specify a different location with the `custom_template_path` option.
### Custom cover page
Using [jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) syntax, you can access all data from your `mkdocs.yml`.
To make template creation easier, you can use `plugin_some_plugin` to access variables from plugins.
E.g. use `{{ author }}` to get the author from your `mkdocs.yml` that looks like:
```yaml
plugins:
- with-pdf:
author: WHO
```
You can use custom variables [`extra:` in your `mkdocs.yml`](https://www.mkdocs.org/user-guide/configuration/#extra)
And, you can check it in the log if run with `verbose` or `debug_html` options.
### Custom stylesheet
Since your stylesheet is appended to the default ones, you can override every setting from them.
Tip: setting the `debug_html` option to `true` to get the generated html that is passed to `weasyprint` can help you determine the html tags, classes or identifiers you want to modify in your stylesheet.
### Advanced Rendering Hooks (Experimental)
You can hook the PDF rendering process by creating a `pdf_event_hook.py`(or `pdf_event_hook/__init__.py`) in your working directory _(usually the same directory as` mkdocs.yml`)_.
_**since**: `v0.8.2`_
#### Sample `pdf_event_hook.py` (or `pdf_event_hook/__init__.py`)
```python
import logging
from bs4 import BeautifulSoup
from mkdocs.structure.pages import Page
def inject_link(html: str, href: str,
page: Page, logger: logging) -> str:
"""Adding PDF View button on navigation bar(using material theme)"""
def _pdf_icon():
_ICON = '''
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<path d="M128,0c-17.6,0-32,14.4-32,32v448c0,17.6,14.4,32,32,32h320c17.6,0,32-14.4,32-32V128L352,0H128z" fill="#E2E5E7"/>
<path d="m384 128h96l-128-128v96c0 17.6 14.4 32 32 32z" fill="#B0B7BD"/>
<polygon points="480 224 384 128 480 128" fill="#CAD1D8"/>
<path d="M416,416c0,8.8-7.2,16-16,16H48c-8.8,0-16-7.2-16-16V256c0-8.8,7.2-16,16-16h352c8.8,0,16,7.2,16,16 V416z" fill="#F15642"/>
<g fill="#fff">
<path d="m101.74 303.15c0-4.224 3.328-8.832 8.688-8.832h29.552c16.64 0 31.616 11.136 31.616 32.48 0 20.224-14.976 31.488-31.616 31.488h-21.36v16.896c0 5.632-3.584 8.816-8.192 8.816-4.224 0-8.688-3.184-8.688-8.816v-72.032zm16.88 7.28v31.872h21.36c8.576 0 15.36-7.568 15.36-15.504 0-8.944-6.784-16.368-15.36-16.368h-21.36z"/>
<path d="m196.66 384c-4.224 0-8.832-2.304-8.832-7.92v-72.672c0-4.592 4.608-7.936 8.832-7.936h29.296c58.464 0 57.184 88.528 1.152 88.528h-30.448zm8.064-72.912v57.312h21.232c34.544 0 36.08-57.312 0-57.312h-21.232z"/>
<path d="m303.87 312.11v20.336h32.624c4.608 0 9.216 4.608 9.216 9.072 0 4.224-4.608 7.68-9.216 7.68h-32.624v26.864c0 4.48-3.184 7.92-7.664 7.92-5.632 0-9.072-3.44-9.072-7.92v-72.672c0-4.592 3.456-7.936 9.072-7.936h44.912c5.632 0 8.96 3.344 8.96 7.936 0 4.096-3.328 8.704-8.96 8.704h-37.248v0.016z"/>
</g>
<path d="m400 432h-304v16h304c8.8 0 16-7.2 16-16v-16c0 8.8-7.2 16-16 16z" fill="#CAD1D8"/>
</svg>
''' # noqa: E501
return BeautifulSoup(_ICON, 'html.parser')
logger.info(f'(hook on inject_link: {page.title})')
soup = BeautifulSoup(html, 'html.parser')
nav = soup.find(class_='md-header-nav')
if not nav:
# after 7.x
nav = soup.find('nav', class_='md-header__inner')
if nav:
a = soup.new_tag('a', href=href, title='PDF',
**{'class': 'md-header__button md-header-nav__button md-icon'})
a.append(_pdf_icon())
nav.append(a)
return str(soup)
return html
# def pre_js_render(soup: BeautifulSoup, logger: logging) -> BeautifulSoup:
# logger.info('(hook on pre_js_render)')
# return soup
# def pre_pdf_render(soup: BeautifulSoup, logger: logging) -> BeautifulSoup:
# logger.info('(hook on pre_pdf_render)')
# tag = soup.find(lambda tag: tag.name ==
# 'body' and 'data-md-color-scheme' in tag.attrs)
# if tag:
# tag['data-md-color-scheme'] = 'print'
# return soup
```
... and check log:
```sh
$ mkdocs build
INFO - Found PDF rendering event hook module.
INFO - Cleaning site directory
INFO - Building documentation to directory: /tmp/sample/site
INFO - (hook on inject_link: Home)
...
```
## 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][github-issues].
If you want to contribute to the code of this project, please read the [Contribution Guidelines][contributing].
## Special thanks to
* [Terry Zhao][zhaoterryy] the author of the [MkDocs PDF Export Plugin][mkdocs-pdf-export-plugin] the source of our inspiration. We've used some of his code in this project.
[mkdocs-pdf-export-plugin]: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin
[zhaoterryy]: https://github.com/zhaoterryy
[weasyprint]: http://weasyprint.org/
[weasyprint-linux]: https://weasyprint.readthedocs.io/en/latest/install.html#linux
[weasyprint-macos]: https://weasyprint.readthedocs.io/en/latest/install.html#os-x
[weasyprint-windows]: https://weasyprint.readthedocs.io/en/latest/install.html#windows
[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/
[mkdocs-material]: https://github.com/squidfunk/mkdocs-material
[contributing]: https://github.com/orzih/mkdocs-with-pdf/blob/master/CONTRIBUTING.md
[github-issues]: https://github.com/orzih/mkdocs-with-pdf/issues
Raw data
{
"_id": null,
"home_page": "https://github.com/tlaguz/mkdocs-to-pdf",
"name": "tlaguz.mkdocs-with-pdf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "mkdocs pdf weasyprint",
"author": "tlaguz",
"author_email": "git@tlaguz.pl",
"download_url": "https://files.pythonhosted.org/packages/63/a0/aa31b2b06b4d88fc0dbf67643a80a46dbe90c0465c3b0c6d43f5800ecca3/tlaguz_mkdocs_with_pdf-20241117.tar.gz",
"platform": null,
"description": "# Important Notice\n\nThis is a private fork of https://github.com/domWalters/mkdocs-to-pdf which hasn't yet published to PyPI. The domWalters' fork is a fork of the original https://github.com/orzih/mkdocs-with-pdf which seems to be abandoned.\n\nI created this fork to be able to use some fixes. You can use it if you want, but I recommend using the original one unless you know what you are doing. I don't guarantee that I will maintain this fork.\n\nTo install this fork, you can use the following command:\n\n```bash\npip install tlaguz.mkdocs-to-pdf\n```\n\n\n# PDF Generate Plugin for MkDocs\n\n[](https://pypi.org/project/mkdocs-with-pdf)\n[](https://pypi.org/project/mkdocs-with-pdf)\n\n---\n\nThis plugin will generate a single PDF file from your MkDocs repository.\nThis plugin is inspired by [MkDocs PDF Export Plugin][mkdocs-pdf-export-plugin].\n\n## Features\n\n* Cover and Table of Contents integrated in the PDF\n* Automatically numbers on heading (h1-h6).\n* Shift down sub-page headings level.\n* using [WeasyPrint][weasyprint].\n\n## Samples\n\n* [PDF of _'MkDocs' docs_][sample_mkdocs]\n* [PDF of _'Material for MkDocs' docs_][sample_mkdocs-material]\n\n[sample_mkdocs]: https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs/README.md\n[sample_mkdocs-material]: https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/README.md\n\n## Requirements\n\n1. This package requires MkDocs version 1.0 or higher (0.17 works as well)\n1. Python 3.6 or higher\n1. WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow the installation instructions for your platform carefully:\n * [Linux][weasyprint-linux]\n * [MacOS][weasyprint-macos]\n * [Windows][weasyprint-windows]\n\n## How to use\n\n### Installation\n\n1. Install the package with pip:\n\n ```bash\n pip install mkdocs-with-pdf\n ```\n\n2. Enable the plugin in your `mkdocs.yml`:\n\n ```yaml\n plugins:\n - with-pdf\n ```\n\n More information about plugins in the [MkDocs documentation][mkdocs-plugins].\n\n#### Testing\n\nWhen building your repository with `mkdocs build`, you should now see the following message at the end of your build output:\n\n> Converting 10 articles to PDF took 7.1s\n\n### Configuration\n\nYou may customize the plugin by passing options in `mkdocs.yml`:\n\n```yaml\nplugins:\n - with-pdf:\n #author: WHO\n #copyright: ANY TEXT\n #\n #cover: false\n #back_cover: true\n #cover_title: TITLE TEXT\n #cover_subtitle: SUBTITLE TEXT\n #custom_template_path: TEMPLATES PATH\n #\n #toc_title: TOC TITLE TEXT\n #heading_shift: false\n #toc_level: 3\n #ordered_chapter_level: 2\n #excludes_children:\n # - 'release-notes/:upgrading'\n # - 'release-notes/:changelog'\n #\n #exclude_pages:\n # - 'bugs/'\n # - 'appendix/contribute/'\n #convert_iframe:\n # - src: IFRAME SRC\n # img: POSTER IMAGE URL\n # text: ALTERNATE TEXT\n # - src: ...\n #two_columns_level: 3\n #\n #render_js: true\n #headless_chrome_path: headless-chromium\n #\n #output_path: any-place/document.pdf\n #enabled_if_env: ENABLE_PDF_EXPORT\n #\n #debug_html: true\n #show_anchors: true\n #verbose: true\n```\n\n#### Options\n\n##### for Properties\n\n* `author`\n\n Set the author text. \n **default**: use `site_author` in your project `mkdocs.yml`\n\n* `copyright`\n\n Set the author text. \n **default**: use `copyright` in your project `mkdocs.yml`\n\n> `author` and `copyright` values are drawn in Cover, and you can use '@page' content. \n>\n> ```css \"e.g.\"\n> @page {\n> @bottom-left {\n> content: string(author) !important;\n> }\n> @bottom-right {\n> content: string(copyright) !important;\n> }\n> }\n> ```\n\n##### for Cover\n\n* `cover`\n\n Set the value to `false` if you don't need a cover page. \n **default**: `true`\n\n* `back_cover`\n\n Set the value to `true` if you need a back cover page. \n **default**: `false` \n _**since**: `v0.8.0`_\n\n You would be better to install the `qrcode` package:\n\n ```sh\n pip install qrcode\n ```\n\n* `cover_title`\n\n Set the title text in cover page. \n **default**: use `site_name` in your project `mkdocs.yml`\n\n* `cover_subtitle`\n\n Set the subtitle text in cover page. \n **default**: `None`\n\n* `cover_logo`\n\n Set the logo image in cover page. This value is URL or simply specify the relative path to the docs directory. \n **default**: `None` \n _**since**: `v0.8.0`_\n\n##### for Heading and TOC\n\n* `toc_title`\n\n Set the title text of _Table of Content_. \n **default**: `Table of Content` \n _**since**: `v0.4.0`_\n\n* `heading_shift`\n\n Set this value to `false`, disable shift heading in child page. \n **default**: `true`\n\n In this flags enable, heading move down one level in child page.\n\n* `toc_level`\n\n Set the level of _Table of Content_. This value is enabled in the range of from `1` to `6`.\n **default**: `3`\n\n* `ordered_chapter_level`\n\n Set the level of heading number addition. This value is enabled in the range of from `1` to `6`.\n **default**: `3`\n\n* `excludes_children`\n\n 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. \n **default**: `[]`\n\n##### for Page\n\n* `exclude_pages`\n\n Set the page `id` of `nav` url. If the `id` matches in this list, it will be excluded page contents. \n **default**: `[]` \n _**since**: `v0.3.0`_\n\n* `convert_iframe`\n\n 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. \n **default**: `[]` \n _**since**: `v0.6.0`_\n\n @see [Sample of _MkDocs Material_](https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/)\n\n* `two_columns_level` (Experimental)\n\n 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. \n\n **default**: `0` \n _**since**: `v0.7.0`_\n\n @see [Sample of _MkDocs Material_](https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/)\n\n##### Renderer for JavaScript\n\n* `render_js`\n\n Set the value to `true` if you're using '[MathJax](https://www.mathjax.org/)', '[Twemoji](https://twemoji.twitter.com/)' or any more. \n Require \"Chrome\" which has \"headless\" mode. \n\n **default**: `false` \n _**since**: `v0.7.0`_\n\n* `headless_chrome_path`\n\n Set the \"Headless Chrome\" program path. \n If `render_js` is _`false`_, this value will be ignored. \n\n **default**: `chromium-browser`\n\n> Check on your system:\n>\n> ```\n> $ <PROGRAM_PATH> --headless \\\n> --disable-gpu \\\n> --dump-dom \\\n> <ANY_SITE_URL(eg. 'https://google.com')>\n> ```\n\n* `relaxedjs_path`\n\n Set the value to execute command of relaxed if you're using e.g. '[Mermaid](https://mermaid-js.github.io) diagrams and Headless Chrome is not working for you.\n Require \"ReLaXed\" Javascript PDF renderer to be installed on your system. See: '[ReLaXed](https://github.com/RelaxedJS/ReLaXed)'.\n\n Please use 'theme_handler_path' option to specify custom JS sources and CSS Stylesheets which covers your needs. E.g. for Material\n theme it would be **material.py**. See: **mkdocs-with-pdf/mkdocs_with_pdf/themes/material.py** for implementation details.\n **default**: `None`\n _**since**: `v0.7.0`_\n\n> Install on your system:\n> ```\n> $ npm i -g relaxedjs\n> $ relaxed --version\n> ```\n\n##### ... and more\n\n* `output_path`\n\n This option allows you to use a different destination for the PDF file. \n **default**: `pdf/document.pdf`\n\n* `custom_template_path`\n\n The path where your custom `cover.html` and/or `styles.scss` are located.\n **default**: `templates` \n _**since**: `v0.8.0`_\n\n* `enabled_if_env`\n\n 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. \n **default**: `None`\n\n PDF generation can take significantly longer than HTML generation which can slow down mkdocs's built-in dev-server.\n\n Adding `enabled_if_env: ENABLE_PDF_EXPORT` under `- with-pdf:` disables PDF generation during development. Run the dev-server normally:\n\n ```sh\n $ mkdocs serve\n INFO - Browser Connected: http://127.0.0.1:8000/\n INFO - Running task: builder (delay: None)\n INFO - Building documentation...\n WARNING - without generate PDF(set environment variable ENABLE_PDF_EXPORT to 1 to enable)\n ... 2 seconds later ...\n INFO - Reload 1 waiters: /.../index.md\n ```\n\n and to build files to deploy specify `ENABLE_PDF_EXPORT=1` at the command line:\n\n ```sh\n $ ENABLE_PDF_EXPORT=1 mkdocs build\n ...\n INFO - Converting 10 articles to PDF took 7.1s\n INFO - Documentation built in 8.29 seconds\n ```\n\n* `debug_html`\n\n Setting this to `true` will out HTML to `stdout` on build time. \n **default**: `false`\n\n You can try this:\n\n ```bash\n mkdocs build > for_pdf_print.html\n ```\n\n ...and browse output with Google Chrome. [Chrome DevTools Into Print Preview Mode](https://developers.google.com/web/tools/chrome-devtools/css/print-preview) will you help.\n\n Note: WeasyPrint and Google Chrome are not fully compatible.\n\n* `show_anchors`\n\n Setting this to `true` will list out of anchor points provided during the build as info message. \n **default**: `false` \n _**since**: `v0.7.4`_\n\n* `verbose`\n\n Setting this to `true` will show all WeasyPrint debug messages during the build. \n **default**: `false`\n\n## Custom cover page and document style\n\nIt is possible to create a custom cover page for the document.\nYou can also add a custom style sheet to modify the whole document.\n\nTo do so, add a `templates` folder at the root level of your `mkdocs` project and place a `cover.html` and/or a `styles.scss` inside.\nAlternatively, you can specify a different location with the `custom_template_path` option.\n\n### Custom cover page\n\nUsing [jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) syntax, you can access all data from your `mkdocs.yml`.\nTo make template creation easier, you can use `plugin_some_plugin` to access variables from plugins.\nE.g. use `{{ author }}` to get the author from your `mkdocs.yml` that looks like:\n\n```yaml\nplugins:\n - with-pdf:\n author: WHO\n```\n\nYou can use custom variables [`extra:` in your `mkdocs.yml`](https://www.mkdocs.org/user-guide/configuration/#extra)\nAnd, you can check it in the log if run with `verbose` or `debug_html` options.\n\n### Custom stylesheet\n\nSince your stylesheet is appended to the default ones, you can override every setting from them.\n\nTip: setting the `debug_html` option to `true` to get the generated html that is passed to `weasyprint` can help you determine the html tags, classes or identifiers you want to modify in your stylesheet.\n\n### Advanced Rendering Hooks (Experimental)\n\nYou can hook the PDF rendering process by creating a `pdf_event_hook.py`(or `pdf_event_hook/__init__.py`) in your working directory _(usually the same directory as` mkdocs.yml`)_. \n_**since**: `v0.8.2`_\n\n#### Sample `pdf_event_hook.py` (or `pdf_event_hook/__init__.py`)\n\n```python\nimport logging\n\nfrom bs4 import BeautifulSoup\nfrom mkdocs.structure.pages import Page\n\n\ndef inject_link(html: str, href: str,\n page: Page, logger: logging) -> str:\n \"\"\"Adding PDF View button on navigation bar(using material theme)\"\"\"\n\n def _pdf_icon():\n _ICON = '''\n<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\">\n<path d=\"M128,0c-17.6,0-32,14.4-32,32v448c0,17.6,14.4,32,32,32h320c17.6,0,32-14.4,32-32V128L352,0H128z\" fill=\"#E2E5E7\"/>\n<path d=\"m384 128h96l-128-128v96c0 17.6 14.4 32 32 32z\" fill=\"#B0B7BD\"/>\n<polygon points=\"480 224 384 128 480 128\" fill=\"#CAD1D8\"/>\n<path d=\"M416,416c0,8.8-7.2,16-16,16H48c-8.8,0-16-7.2-16-16V256c0-8.8,7.2-16,16-16h352c8.8,0,16,7.2,16,16 V416z\" fill=\"#F15642\"/>\n<g fill=\"#fff\">\n<path d=\"m101.74 303.15c0-4.224 3.328-8.832 8.688-8.832h29.552c16.64 0 31.616 11.136 31.616 32.48 0 20.224-14.976 31.488-31.616 31.488h-21.36v16.896c0 5.632-3.584 8.816-8.192 8.816-4.224 0-8.688-3.184-8.688-8.816v-72.032zm16.88 7.28v31.872h21.36c8.576 0 15.36-7.568 15.36-15.504 0-8.944-6.784-16.368-15.36-16.368h-21.36z\"/>\n<path d=\"m196.66 384c-4.224 0-8.832-2.304-8.832-7.92v-72.672c0-4.592 4.608-7.936 8.832-7.936h29.296c58.464 0 57.184 88.528 1.152 88.528h-30.448zm8.064-72.912v57.312h21.232c34.544 0 36.08-57.312 0-57.312h-21.232z\"/>\n<path d=\"m303.87 312.11v20.336h32.624c4.608 0 9.216 4.608 9.216 9.072 0 4.224-4.608 7.68-9.216 7.68h-32.624v26.864c0 4.48-3.184 7.92-7.664 7.92-5.632 0-9.072-3.44-9.072-7.92v-72.672c0-4.592 3.456-7.936 9.072-7.936h44.912c5.632 0 8.96 3.344 8.96 7.936 0 4.096-3.328 8.704-8.96 8.704h-37.248v0.016z\"/>\n</g>\n<path d=\"m400 432h-304v16h304c8.8 0 16-7.2 16-16v-16c0 8.8-7.2 16-16 16z\" fill=\"#CAD1D8\"/>\n</svg>\n''' # noqa: E501\n return BeautifulSoup(_ICON, 'html.parser')\n\n logger.info(f'(hook on inject_link: {page.title})')\n soup = BeautifulSoup(html, 'html.parser')\n\n nav = soup.find(class_='md-header-nav')\n if not nav:\n # after 7.x\n nav = soup.find('nav', class_='md-header__inner')\n if nav:\n a = soup.new_tag('a', href=href, title='PDF',\n **{'class': 'md-header__button md-header-nav__button md-icon'})\n a.append(_pdf_icon())\n nav.append(a)\n return str(soup)\n\n return html\n\n\n# def pre_js_render(soup: BeautifulSoup, logger: logging) -> BeautifulSoup:\n# logger.info('(hook on pre_js_render)')\n# return soup\n\n\n# def pre_pdf_render(soup: BeautifulSoup, logger: logging) -> BeautifulSoup:\n# logger.info('(hook on pre_pdf_render)')\n# tag = soup.find(lambda tag: tag.name ==\n# 'body' and 'data-md-color-scheme' in tag.attrs)\n# if tag:\n# tag['data-md-color-scheme'] = 'print'\n# return soup\n```\n\n... and check log:\n\n```sh\n$ mkdocs build\nINFO - Found PDF rendering event hook module.\nINFO - Cleaning site directory\nINFO - Building documentation to directory: /tmp/sample/site\nINFO - (hook on inject_link: Home)\n ...\n```\n\n## Contributing\n\nFrom reporting a bug to submitting a pull request: every contribution is appreciated and welcome. Report bugs, ask questions and request features using [Github issues][github-issues].\nIf you want to contribute to the code of this project, please read the [Contribution Guidelines][contributing].\n\n## Special thanks to\n\n* [Terry Zhao][zhaoterryy] the author of the [MkDocs PDF Export Plugin][mkdocs-pdf-export-plugin] the source of our inspiration. We've used some of his code in this project.\n\n[mkdocs-pdf-export-plugin]: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin\n[zhaoterryy]: https://github.com/zhaoterryy\n\n[weasyprint]: http://weasyprint.org/\n[weasyprint-linux]: https://weasyprint.readthedocs.io/en/latest/install.html#linux\n[weasyprint-macos]: https://weasyprint.readthedocs.io/en/latest/install.html#os-x\n[weasyprint-windows]: https://weasyprint.readthedocs.io/en/latest/install.html#windows\n\n[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/\n[mkdocs-material]: https://github.com/squidfunk/mkdocs-material\n\n[contributing]: https://github.com/orzih/mkdocs-with-pdf/blob/master/CONTRIBUTING.md\n[github-issues]: https://github.com/orzih/mkdocs-with-pdf/issues\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate a single PDF file from MkDocs repository",
"version": "20241117",
"project_urls": {
"Homepage": "https://github.com/tlaguz/mkdocs-to-pdf"
},
"split_keywords": [
"mkdocs",
"pdf",
"weasyprint"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0c2d4126f67d591bdd58c0127df958c5a65d68ad96f869d48ace3bee0a34ed7",
"md5": "650757e0d54af10794a978fcbe9a2848",
"sha256": "403f0574b7ecbd80b816683a77abecef2ba1eef2c835c671b2233c51475a7d73"
},
"downloads": -1,
"filename": "tlaguz.mkdocs_with_pdf-20241117-py3-none-any.whl",
"has_sig": false,
"md5_digest": "650757e0d54af10794a978fcbe9a2848",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 48039,
"upload_time": "2024-11-17T21:24:52",
"upload_time_iso_8601": "2024-11-17T21:24:52.659854Z",
"url": "https://files.pythonhosted.org/packages/b0/c2/d4126f67d591bdd58c0127df958c5a65d68ad96f869d48ace3bee0a34ed7/tlaguz.mkdocs_with_pdf-20241117-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "63a0aa31b2b06b4d88fc0dbf67643a80a46dbe90c0465c3b0c6d43f5800ecca3",
"md5": "c92a5db40595c09c6206865b273ca6b7",
"sha256": "7e6ebb951794b40dda2b21ba0d030ccc613821619ed7b087545bc76e5f896305"
},
"downloads": -1,
"filename": "tlaguz_mkdocs_with_pdf-20241117.tar.gz",
"has_sig": false,
"md5_digest": "c92a5db40595c09c6206865b273ca6b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 44935,
"upload_time": "2024-11-17T21:24:54",
"upload_time_iso_8601": "2024-11-17T21:24:54.628685Z",
"url": "https://files.pythonhosted.org/packages/63/a0/aa31b2b06b4d88fc0dbf67643a80a46dbe90c0465c3b0c6d43f5800ecca3/tlaguz_mkdocs_with_pdf-20241117.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-17 21:24:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tlaguz",
"github_project": "mkdocs-to-pdf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tlaguz.mkdocs-with-pdf"
}
JSON
