# CM MkDocs Plugins - 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.
This was forked from the great work done by <https://github.com/brospars/mkdocs-page-pdf> and changed to allow individual PDF export instead of excluding paths from export, due to the need to speed up the PDF generation process for a vast number of files and an issue with the glob pattern used for the exclude parameter, since the plugin implementation of PurePath.match doesn't match recursively so we have to specify all possible paths to exclude, significantly slowing down the process. Parsing the FrontMatter YAML to search for a specific key:value speeds the process immensely.
## How to use
Install the package with pip:
```shell
pip install mkdocs-cm-page-to-pdf
```
Enable the plugin in your mkdocs.yml:
```yaml
plugins:
# - ...
- mkdocs-cm-page-to-pdf # should be last
```
### Options
To set different options use the following syntax.
```yaml
plugins:
# - ...
- mkdocs-cm-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](https://pyppeteer.github.io/pyppeteer/reference.html?highlight=pdf#pyppeteer.page.Page.pdf) :
* ``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 to``False``.
* ``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](https://pyppeteer.github.io/pyppeteer/reference.html?highlight=goto#pyppeteer.page.Page.goto)).
* ``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. Disregarded when ``include`` is set to ``True``.
* ``include`` (bool) : Manually define files to export. Defaults to ``False``.
If using the `include` option, insert a `pdfexport: true` key in the FrontMatter YAML of any Markdown file you wish to export to PDF. Example:
```yaml
---
pdfexport: true
---
```
### 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 libraries used by Chrome Headless.
Related issue: <https://github.com/pyppeteer/pyppeteer/issues/194>
See this [article](https://www.cloudsavvyit.com/13461/how-to-run-puppeteer-and-headless-chrome-in-a-docker-container/)
and this [guide](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-puppeteer-in-docker)
#### 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](https://github.com/brospars/mkdocs-page-pdf/issues/9) a blank page can appear at the end of the PDF you can remove it by adding the following to you extra.css :
```css
body {
contain: strict;
}
```
## Special thanks
The original version of this plugin (here: <https://github.com/brospars/mkdocs-page-pdf>) was inspired by [mkdocs-with-pdf](https://github.com/orzih/mkdocs-with-pdf) and [mkdocs-pdf-export-plugin](https://github.com/zhaoterryy/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.
Raw data
{
"_id": null,
"home_page": "https://github.com/usulpt/mkdocs-cm-page-to-pdf",
"name": "mkdocs-cm-page-to-pdf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "mkdocs pdf pyppeteer chrome headless page",
"author": "usulpt",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ed/b5/aa8cccc4aa9283e3b6666775dfb5d93815099b4f17b0466bb88b377d1ee4/mkdocs_cm_page_to_pdf-0.1.5.tar.gz",
"platform": null,
"description": "# CM MkDocs Plugins - MkDocs Page to PDF\r\n\r\nAn MkDocs plugin to generate a PDF file for each MkDocs page using `pyppeteer` (chrome headless) and add a download button.\r\n\r\nThis was forked from the great work done by <https://github.com/brospars/mkdocs-page-pdf> and changed to allow individual PDF export instead of excluding paths from export, due to the need to speed up the PDF generation process for a vast number of files and an issue with the glob pattern used for the exclude parameter, since the plugin implementation of PurePath.match doesn't match recursively so we have to specify all possible paths to exclude, significantly slowing down the process. Parsing the FrontMatter YAML to search for a specific key:value speeds the process immensely.\r\n\r\n## How to use\r\n\r\nInstall the package with pip:\r\n\r\n```shell\r\npip install mkdocs-cm-page-to-pdf\r\n```\r\n\r\nEnable the plugin in your mkdocs.yml:\r\n\r\n```yaml\r\nplugins:\r\n # - ...\r\n - mkdocs-cm-page-to-pdf # should be last\r\n```\r\n\r\n### Options\r\n\r\nTo set different options use the following syntax.\r\n\r\n```yaml\r\nplugins:\r\n # - ...\r\n - mkdocs-cm-page-to-pdf:\r\n # Options here\r\n```\r\n\r\n* ``disable`` (bool): Disable pdf rendering useful to quickly disable it without removing the plugin config. Defaults to ``False``.\r\n* ``disableOnServe`` (bool): Disable pdf rendering when using `mkdocs serve`. Defaults to ``False``.\r\n\r\nThe following options are directly induced from [pyppeteer options](https://pyppeteer.github.io/pyppeteer/reference.html?highlight=pdf#pyppeteer.page.Page.pdf) :\r\n\r\n* ``scale`` (float): Scale of the webpage rendering, defaults to ``1.0``.\r\n* ``displayHeaderFooter`` (bool): Display header and footer.\r\n Defaults to ``False``.\r\n* ``headerTemplate`` (str): HTML template for the print header. Should\r\n be valid HTML markup with following classes.\r\n * ``date``: formatted print date\r\n * ``title``: document title\r\n * ``url``: document location\r\n * ``pageNumber``: current page number\r\n * ``totalPages``: total pages in the document\r\n* ``footerTemplate`` (str): HTML template for the print footer. Should be valid HTML markup with the same classes as ``headerTemplate``.\r\n* ``printBackground`` (bool): Print background graphics. Defaults to``False``.\r\n* ``landscape`` (bool): Paper orientation. Defaults to ``False``.\r\n* ``pageRanges`` (string): Paper ranges to print, e.g., '1-5,8,11-13'. Defaults to empty string, which means all pages.\r\n* ``format`` (str): Paper format. Defaults to ``A4``.\r\n* ``margin`` (dict): Paper margins.\r\n * ``top`` (str): Top margin, accepts values labeled with units, defaults to ``20px``.\r\n * ``right`` (str): Right margin, accepts values labeled with units, defaults to ``20px``.\r\n * ``bottom`` (str): Bottom margin, accepts values labeled with units, defaults to ``20px``.\r\n * ``left`` (str): Left margin, accepts values labeled with units, defaults to ``20px``.\r\n* ``pageLoadOptions`` (dict): Page load options (see [this](https://pyppeteer.github.io/pyppeteer/reference.html?highlight=goto#pyppeteer.page.Page.goto)).\r\n * ``timeout`` (int): Maximum time in milliseconds, defaults to ``30000``.\r\n * ``waitUntil`` (str): When to consider navigation succeeded, defaults to ``load``.\r\n* ``exclude`` (list) : List of glob pattern to exclude. Disregarded when ``include`` is set to ``True``.\r\n* ``include`` (bool) : Manually define files to export. Defaults to ``False``.\r\n\r\nIf using the `include` option, insert a `pdfexport: true` key in the FrontMatter YAML of any Markdown file you wish to export to PDF. Example:\r\n\r\n```yaml\r\n---\r\npdfexport: true\r\n---\r\n```\r\n\r\n### Troubleshooting\r\n\r\n#### Running in a docker container (ci/cd)\r\n\r\nDepending on what image you are using you may encounter some issue running `pyppeteer` : `Browser closed unexpectedly`.\r\n\r\nThis is due to some missing shared libraries used by Chrome Headless.\r\n\r\nRelated issue: <https://github.com/pyppeteer/pyppeteer/issues/194>\r\n\r\nSee this [article](https://www.cloudsavvyit.com/13461/how-to-run-puppeteer-and-headless-chrome-in-a-docker-container/)\r\nand this [guide](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-puppeteer-in-docker) \r\n\r\n#### Slow build on serve\r\n\r\nYou 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.\r\n\r\n#### Blank page at the end\r\n\r\nDue to a [chrome bug](https://github.com/brospars/mkdocs-page-pdf/issues/9) a blank page can appear at the end of the PDF you can remove it by adding the following to you extra.css :\r\n\r\n```css\r\nbody {\r\n contain: strict;\r\n}\r\n```\r\n\r\n## Special thanks\r\n\r\nThe original version of this plugin (here: <https://github.com/brospars/mkdocs-page-pdf>) was inspired by [mkdocs-with-pdf](https://github.com/orzih/mkdocs-with-pdf) and [mkdocs-pdf-export-plugin](https://github.com/zhaoterryy/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.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate a PDF file for each MkDocs page, with the possibility of selecting individual pages for export",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/usulpt/mkdocs-cm-page-to-pdf"
},
"split_keywords": [
"mkdocs",
"pdf",
"pyppeteer",
"chrome",
"headless",
"page"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "796ad44c7802f6bd96022a0f4637bf10d2f1b7dd85d1878937e5f20eee6c1c3f",
"md5": "fb2aec0e7a9fd9bf8ff71cd6096fdf7b",
"sha256": "0ac98cc18f7cccb96f7167f0e19e2a0804a3e7b573bc0822b2567465a503475d"
},
"downloads": -1,
"filename": "mkdocs_cm_page_to_pdf-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb2aec0e7a9fd9bf8ff71cd6096fdf7b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9185,
"upload_time": "2024-07-11T14:32:49",
"upload_time_iso_8601": "2024-07-11T14:32:49.663161Z",
"url": "https://files.pythonhosted.org/packages/79/6a/d44c7802f6bd96022a0f4637bf10d2f1b7dd85d1878937e5f20eee6c1c3f/mkdocs_cm_page_to_pdf-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "edb5aa8cccc4aa9283e3b6666775dfb5d93815099b4f17b0466bb88b377d1ee4",
"md5": "c1f711417c09e3937e78c9e8a071dc7c",
"sha256": "22023d75c0d2eb88c68ee43a844d16d9b7471f953885e9738f94bce7bbc5d27e"
},
"downloads": -1,
"filename": "mkdocs_cm_page_to_pdf-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "c1f711417c09e3937e78c9e8a071dc7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6387,
"upload_time": "2024-07-11T14:32:51",
"upload_time_iso_8601": "2024-07-11T14:32:51.917423Z",
"url": "https://files.pythonhosted.org/packages/ed/b5/aa8cccc4aa9283e3b6666775dfb5d93815099b4f17b0466bb88b377d1ee4/mkdocs_cm_page_to_pdf-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-11 14:32:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "usulpt",
"github_project": "mkdocs-cm-page-to-pdf",
"github_not_found": true,
"lcname": "mkdocs-cm-page-to-pdf"
}
JSON
