# MkPDFs v2 for MkDocs
> :bangbang: This is a fork of original comwes/mkpdfs-mkdocs-plugin
>
> :exclamation: There could be many things that are not up-to-date, but at this moment (20.09.2023) this plugin should work.
*It's a MkDocs plugin that export your documentation in a single PDF file*
[][mkpdfsdoc]
The MkPDFs plugin will export yor documentation in your MkDocs repository as a PDF file using [WeasyPrint](http://weasyprint.org/).
Unlike other plugin where customizing the design of the generated PDF is complicated, this plugin brings the ability to completely control the design of the generated PDF.
What makes this plugin particular, is that:
1. Your documentation is exported as a single PDF file
2. The order of pages fits the navigation as defined in the MkDocs configuration file
3. The ability to override the default design to make it fit your needs
4. The ability to exclude some files from the generated PDF
5. No layout issues
6. No conflict with the theme design
7. Table of contents integrated in the PDF
## Requirements
1. This package requires MkDocs version 1.0
2. Python 3.4 or higher
3. WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow your platform installation instructions carefully:
- [Linux][weasyprint-linux]
- [MacOS][weasyprint-macos]
- [Windows][weasyprint-windows]
## Limitation
The PDF version of the documentation will not be created if the used generated page content's is not enclosed in an `<article>` tag or in a `<div>` tag with property `role="main"`.
## Installation
Install the package with `pip`:
```bash
pip3 install mkpdfs2-mkdocs
```
Enable the plugin in your `mkdocs.yml` as folowing
```yaml
plugins:
- search
- mkpdfs
```
or with options
```yaml
plugins:
- search
- mkpdfs:
- company: The War Company Inc.
- author: Monsieur Silvestre
```
> **Note:** If you enable this plugin and you don't have `plugins` entry in your MkDocs config file yet, you will need to explicitly enable the `search` plugin. This plugin is enabled by default when no `plugins` entry is set.
You can find further information about plugins in the [MkDocs documentation][mkdocs-plugins].
## How does it work?
When building or serving your documentation with `mkdocs build` or `mkdocs serve`, the following message will be displayed if everything wend smoothly:
> The PDF version of the documentation has been generated.
## Options
This plugin supports following options to allow you better handle the customisation of the generated PDF.
| Option | Description |
| --- | --- |
| `author` | The author of the document. This information will be printed on the cover page of the generated PDF. |
| `company` | If this documentation is from a company, then you should provide this information. It will be displayed on the front page of the documentation, bellow the author information|
| `toc_title` | The table of content title. The default value is **Table of Contents** |
| `toc_position` | The position of the table of contents. This option supports 3 differents values: `pre` to put the toc at the beginning of the file but after the cover (**the default value**), `post` to put it at the end of the file or `none` to not generate it at all. |
| `output_path` | The file name of the generated PDF, relative to the `site_dir`. By default this location is set to `pdf/combined.pdf`|
| `pdf_links` | Create link to download the generated PDF to the top of each HTML page. By default this is enabled |
| `design` | Relative to your `MkDocs repository`, this option is the location of the CSS file defining the layout of the generated PDF. If this option is not defined the default design will be used. Defining an non existing file will cause the build or serve failure. |
| `generate_html` | Save the html from which the PDF is generated to be able to debug it in the browser. Default is 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][github-issues].
## Thanks to
The idea of this plugin has raised while working on a project in the public sector. After many research I found some plugins that guided me to the current solution. They have inspired me a lot, so many 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.
- [Kozea team][kozeateam] for bringing [WeasyPrint](https://github.com/Kozea/WeasyPrint) to us as an open source project. The default design of the generated PDF is based on their work [report Sample](https://github.com/Kozea/WeasyPrint/tree/gh-pages/samples/report).
- [Martin Donath][squidfunk] the author of [Material for MkDocs][materialmkdoc], some of his css file were used to design the layout of Admonition, Codehilite, Arthmatex, emoji, and more.
- [Gerry Ntabuhashe][comwes] the author of the original mkpdfs plugin.
[weasyprint-linux]: https://weasyprint.readthedocs.io/en/latest/install.html#linux
[weasyprint-macos]: https://weasyprint.readthedocs.io/en/latest/install.html#macos
[weasyprint-windows]: https://weasyprint.readthedocs.io/en/latest/install.html#windows
[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/
[github-issues]: https://github.com/comwes/mkpdfs-mkdocs-plugin/issues
[contributing]: CONTRIBUTING.md
[mkdocs-pdf-export-plugin]: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin
[kozeateam]: https://github.com/Kozea
[zhaoterryy]: https://github.com/zhaoterryy
[squidfunk]: https://github.com/squidfunk
[materialmkdoc]: https://github.com/squidfunk/mkdocs-material
Raw data
{
"_id": null,
"home_page": "https://github.com/jurgenwigg/mkpdfs2-mkdocs-plugin",
"name": "mkpdfs2-mkdocs",
"maintainer": "jurgenwigg",
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": "jurgenwigg@protonmail.com",
"keywords": "mkdocs documentation pdf export weasyprint markdown plugin",
"author": "Comwes",
"author_email": "contact@comwes.eu",
"download_url": "https://files.pythonhosted.org/packages/7d/a9/18adc567129dff96c5155286f94b6c436e49970da7f9ea5d3d1d0fed38fe/mkpdfs2-mkdocs-1.1.1.tar.gz",
"platform": null,
"description": "# MkPDFs v2 for MkDocs \n\n> :bangbang: This is a fork of original comwes/mkpdfs-mkdocs-plugin\n> \n> :exclamation: There could be many things that are not up-to-date, but at this moment (20.09.2023) this plugin should work.\n\n*It's a MkDocs plugin that export your documentation in a single PDF file*\n\n[][mkpdfsdoc]\n\nThe MkPDFs plugin will export yor documentation in your MkDocs repository as a PDF file using [WeasyPrint](http://weasyprint.org/).\n\nUnlike other plugin where customizing the design of the generated PDF is complicated, this plugin brings the ability to completely control the design of the generated PDF.\n\nWhat makes this plugin particular, is that:\n\n1. Your documentation is exported as a single PDF file\n2. The order of pages fits the navigation as defined in the MkDocs configuration file\n3. The ability to override the default design to make it fit your needs\n4. The ability to exclude some files from the generated PDF\n5. No layout issues\n6. No conflict with the theme design\n7. Table of contents integrated in the PDF\n\n## Requirements\n\n1. This package requires MkDocs version 1.0\n2. Python 3.4 or higher\n3. WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow your platform installation instructions carefully:\n - [Linux][weasyprint-linux]\n - [MacOS][weasyprint-macos]\n - [Windows][weasyprint-windows]\n\n## Limitation\n\nThe PDF version of the documentation will not be created if the used generated page content's is not enclosed in an `<article>` tag or in a `<div>` tag with property `role=\"main\"`.\n\n## Installation\n\nInstall the package with `pip`:\n\n```bash\npip3 install mkpdfs2-mkdocs\n```\n\nEnable the plugin in your `mkdocs.yml` as folowing\n\n```yaml\nplugins:\n - search\n - mkpdfs\n```\n\nor with options\n\n```yaml\nplugins:\n - search\n - mkpdfs:\n - company: The War Company Inc.\n - author: Monsieur Silvestre\n```\n\n> **Note:** If you enable this plugin and you don't have `plugins` entry in your MkDocs config file yet, you will need to explicitly enable the `search` plugin. This plugin is enabled by default when no `plugins` entry is set.\n\nYou can find further information about plugins in the [MkDocs documentation][mkdocs-plugins].\n\n## How does it work?\n\nWhen building or serving your documentation with `mkdocs build` or `mkdocs serve`, the following message will be displayed if everything wend smoothly:\n\n> The PDF version of the documentation has been generated.\n\n## Options\n\nThis plugin supports following options to allow you better handle the customisation of the generated PDF.\n\n\n| Option | Description |\n| --- | --- |\n| `author` | The author of the document. This information will be printed on the cover page of the generated PDF. |\n| `company` | If this documentation is from a company, then you should provide this information. It will be displayed on the front page of the documentation, bellow the author information|\n| `toc_title` | The table of content title. The default value is **Table of Contents** |\n| `toc_position` | The position of the table of contents. This option supports 3 differents values: `pre` to put the toc at the beginning of the file but after the cover (**the default value**), `post` to put it at the end of the file or `none` to not generate it at all. |\n| `output_path` | The file name of the generated PDF, relative to the `site_dir`. By default this location is set to `pdf/combined.pdf`|\n| `pdf_links` | Create link to download the generated PDF to the top of each HTML page. By default this is enabled |\n| `design` | Relative to your `MkDocs repository`, this option is the location of the CSS file defining the layout of the generated PDF. If this option is not defined the default design will be used. Defining an non existing file will cause the build or serve failure. |\n| `generate_html` | Save the html from which the PDF is generated to be able to debug it in the browser. Default is False |\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].\n\n\n## Thanks to\n\nThe idea of this plugin has raised while working on a project in the public sector. After many research I found some plugins that guided me to the current solution. They have inspired me a lot, so many 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- [Kozea team][kozeateam] for bringing [WeasyPrint](https://github.com/Kozea/WeasyPrint) to us as an open source project. The default design of the generated PDF is based on their work [report Sample](https://github.com/Kozea/WeasyPrint/tree/gh-pages/samples/report).\n- [Martin Donath][squidfunk] the author of [Material for MkDocs][materialmkdoc], some of his css file were used to design the layout of Admonition, Codehilite, Arthmatex, emoji, and more.\n- [Gerry Ntabuhashe][comwes] the author of the original mkpdfs plugin.\n\n[weasyprint-linux]: https://weasyprint.readthedocs.io/en/latest/install.html#linux\n[weasyprint-macos]: https://weasyprint.readthedocs.io/en/latest/install.html#macos\n[weasyprint-windows]: https://weasyprint.readthedocs.io/en/latest/install.html#windows\n[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/\n[github-issues]: https://github.com/comwes/mkpdfs-mkdocs-plugin/issues\n[contributing]: CONTRIBUTING.md\n[mkdocs-pdf-export-plugin]: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin\n[kozeateam]: https://github.com/Kozea\n[zhaoterryy]: https://github.com/zhaoterryy\n[squidfunk]: https://github.com/squidfunk\n[materialmkdoc]: https://github.com/squidfunk/mkdocs-material\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Allows the generation of the PDF version of your MkDocs documentation.",
"version": "1.1.1",
"project_urls": {
"Bug Reports": "https://github.com/jurgenwigg/mkpdfs2-mkdocs-plugin/issues",
"Homepage": "https://github.com/jurgenwigg/mkpdfs2-mkdocs-plugin",
"Source": "https://github.com/jurgenwigg/mkpdfs2-mkdocs-plugin"
},
"split_keywords": [
"mkdocs",
"documentation",
"pdf",
"export",
"weasyprint",
"markdown",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "91c1c9c085f38984c5ecc1681c023556c1a15a0703292f491c19678e7e3ebc39",
"md5": "eb2f1856132899498b428280d066ab69",
"sha256": "5f3dfb41dc93742c99faaea450680a46010ff601cd8e3af945c373441375e77a"
},
"downloads": -1,
"filename": "mkpdfs2_mkdocs-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb2f1856132899498b428280d066ab69",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 1763097,
"upload_time": "2023-10-06T08:59:01",
"upload_time_iso_8601": "2023-10-06T08:59:01.092430Z",
"url": "https://files.pythonhosted.org/packages/91/c1/c9c085f38984c5ecc1681c023556c1a15a0703292f491c19678e7e3ebc39/mkpdfs2_mkdocs-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7da918adc567129dff96c5155286f94b6c436e49970da7f9ea5d3d1d0fed38fe",
"md5": "2be9219aaf0f156304ccdb23f18c35e3",
"sha256": "327da5f02c5f9426955c4ffe6707736021f80c4aa3657ebc4e49f17f3e48ec39"
},
"downloads": -1,
"filename": "mkpdfs2-mkdocs-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "2be9219aaf0f156304ccdb23f18c35e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 1763530,
"upload_time": "2023-10-06T08:59:02",
"upload_time_iso_8601": "2023-10-06T08:59:02.923270Z",
"url": "https://files.pythonhosted.org/packages/7d/a9/18adc567129dff96c5155286f94b6c436e49970da7f9ea5d3d1d0fed38fe/mkpdfs2-mkdocs-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-06 08:59:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jurgenwigg",
"github_project": "mkpdfs2-mkdocs-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkpdfs2-mkdocs"
}
JSON
