# 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.
## How to use
Install the package with pip:
```shell
pip install mkdocs-page-pdf
```
Enable the plugin in your mkdocs.yml:
```yaml
plugins:
# - ...
- page-to-pdf # should be last
```
### Options
To set different options use the following syntax.
```yaml
plugins:
# - ...
- 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 use the same template 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
### 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 librairies 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)
Ready-to-use docker image : https://github.com/brospars/docker-mkdocs
#### 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.
## Special thanks
This plugin 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/brospars/mkdocs-page-pdf",
"name": "mkdocs-page-pdf",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "mkdocs pdf pyppeteer chrome headless page",
"author": "brospars",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/d1/39/4aeb3558ed7ddad0bc5bf734691bd37b95ae5ef68aabb8636dc5547eb564/mkdocs-page-pdf-0.1.0.tar.gz",
"platform": null,
"description": "# Mkdocs Page to PDF\n\nAn Mkdocs plugin to generate a PDF file for each MkDocs page using `pyppeteer` (chrome headless) \nand add a download button.\n\n## How to use\n\nInstall the package with pip:\n\n```shell\npip install mkdocs-page-pdf\n```\n\nEnable the plugin in your mkdocs.yml:\n\n```yaml\nplugins:\n # - ...\n - page-to-pdf # should be last\n```\n\n### Options\nTo set different options use the following syntax.\n```yaml\nplugins:\n # - ...\n - page-to-pdf :\n # Options here\n```\n* ``disable`` (bool): Disable pdf rendering useful to quickly disable it without removing the plugin config. Defaults to ``False``.\n* ``disableOnServe`` (bool): Disable pdf rendering when using `mkdocs serve`. Defaults to ``False``.\n\nThe following options are directly induced from [pyppeteer options](https://pyppeteer.github.io/pyppeteer/reference.html?highlight=pdf#pyppeteer.page.Page.pdf) :\n\n* ``scale`` (float): Scale of the webpage rendering, defaults to ``1.0``.\n* ``displayHeaderFooter`` (bool): Display header and footer.\n Defaults to ``False``.\n* ``headerTemplate`` (str): HTML template for the print header. Should\n be valid HTML markup with following classes.\n * ``date``: formatted print date\n * ``title``: document title\n * ``url``: document location\n * ``pageNumber``: current page number\n * ``totalPages``: total pages in the document\n* ``footerTemplate`` (str): HTML template for the print footer. Should use the same template as ``headerTemplate``.\n* ``printBackground`` (bool): Print background graphics. Defaults to``False``.\n* ``landscape`` (bool): Paper orientation. Defaults to ``False``.\n* ``pageRanges`` (string): Paper ranges to print, e.g., '1-5,8,11-13'. Defaults to empty string, which means all pages.\n* ``format`` (str): Paper format. Defaults to ``A4``.\n* ``margin`` (dict): Paper margins.\n * ``top`` (str): Top margin, accepts values labeled with units, defaults to ``20px``.\n * ``right`` (str): Right margin, accepts values labeled with units, defaults to ``20px``.\n * ``bottom`` (str): Bottom margin, accepts values labeled with units, defaults to ``20px``.\n * ``left`` (str): Left margin, accepts values labeled with units, defaults to ``20px``.\n* ``pageLoadOptions`` (dict): Page load options (see [this](https://pyppeteer.github.io/pyppeteer/reference.html?highlight=goto#pyppeteer.page.Page.goto)).\n * ``timeout`` (int): Maximum time in milliseconds, defaults to ``30000``.\n * ``waitUntil`` (str): When to consider navigation succeeded, defaults to ``load``.\n* ``exclude`` (list) : List of glob pattern to exclude\n\n### Troubleshooting\n\n#### Running in a docker container (ci/cd) \n\nDepending on what image you are using you may encounter some issue running `pyppeteer` : `Browser closed unexpectedly`\nThis is due to some missing shared librairies used by Chrome Headless. \n\nRelated issue : https://github.com/pyppeteer/pyppeteer/issues/194 \nSee this [article](https://www.cloudsavvyit.com/13461/how-to-run-puppeteer-and-headless-chrome-in-a-docker-container/)\nand this [guide](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-puppeteer-in-docker) \nReady-to-use docker image : https://github.com/brospars/docker-mkdocs\n\n#### Slow build on serve\n\nYou can use `disable` or `disableOnServe` options to disable the pdf rendering (entirely or on serve) but you can also \nuse the `mkdocs serve --dirtyreload` flag to only rebuild modified files on the fly.\n\n## Special thanks\n\nThis plugin was inspired by [mkdocs-with-pdf](https://github.com/orzih/mkdocs-with-pdf)\nand [mkdocs-pdf-export-plugin](https://github.com/zhaoterryy/mkdocs-pdf-export-plugin)\nbut without using `weasyprint` and instead `pyppeteer` (chrome headless) to have a render \ncloser to what you have in your chrome browser.\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate a PDF file for each MkDocs page",
"version": "0.1.0",
"split_keywords": [
"mkdocs",
"pdf",
"pyppeteer",
"chrome",
"headless",
"page"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "5bea3cddfa02d4a3a42c8325c6ccd45a",
"sha256": "28b8be235b0771f53dbe01d16cce98fc16522dc751c20b730329cadfea0200d4"
},
"downloads": -1,
"filename": "mkdocs_page_pdf-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5bea3cddfa02d4a3a42c8325c6ccd45a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6154,
"upload_time": "2022-03-22T14:58:33",
"upload_time_iso_8601": "2022-03-22T14:58:33.674592Z",
"url": "https://files.pythonhosted.org/packages/5e/a2/6b04ba343c726325a08c3f4d490611b1586a8d96f285629e43a4c6283aee/mkdocs_page_pdf-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "7fa32522448a12fd8d0b443edeaa027e",
"sha256": "8f97a4b8d63bfb818a1d3c303af5c701b329f611fc2b13c834fe4ea4140977e5"
},
"downloads": -1,
"filename": "mkdocs-page-pdf-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7fa32522448a12fd8d0b443edeaa027e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5247,
"upload_time": "2022-03-22T14:58:37",
"upload_time_iso_8601": "2022-03-22T14:58:37.660885Z",
"url": "https://files.pythonhosted.org/packages/d1/39/4aeb3558ed7ddad0bc5bf734691bd37b95ae5ef68aabb8636dc5547eb564/mkdocs-page-pdf-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-03-22 14:58:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "brospars",
"github_project": "mkdocs-page-pdf",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "asyncio",
"specs": []
},
{
"name": "nest_asyncio",
"specs": []
},
{
"name": "pyppeteer",
"specs": []
},
{
"name": "mkdocs",
"specs": []
}
],
"lcname": "mkdocs-page-pdf"
}
JSON
