允许生成mkdocs文档的pdf版本。
mkpdfs-mkdocs的Python项目详细描述
mkdocs的mkpdfs
这是一个mkdocs插件,可以将文档导出到一个pdf文件中
mkpdfs插件将使用WeasyPrint将mkdocs存储库中的文档导出为pdf文件。
与其他定制生成pdf的设计很复杂的插件不同,这个插件带来了完全控制生成pdf的设计的能力。
这个插件的特殊之处在于:
- 您的文档将作为单个pdf文件导出
- 页面顺序符合mkdocs配置文件中定义的导航
- 能够覆盖默认设计,使其满足您的需要
- 从生成的pdf中排除某些文件的能力
- 无布局问题
- 与主题设计没有冲突
- 集成在pdf中的目录
要求
- 此软件包需要mkdocs 1.0版
- python 3.4或更高版本
- weasyprint依赖于cairo、pango和gdk pixbuf,它们需要单独安装。请仔细遵循平台安装说明:
限制
如果使用的生成页面内容未包含在<article>
标记或具有属性role="main"
的<div>
标记中,则不会创建文档的pdf版本。
安装
用pip
:
pip3 install mkpdfs-mkdocs
在mkdocs.yml
中启用插件,如下所示
plugins:-search-mkpdfs
或使用选项
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 thesearch
plugin. This plugin is enabled by default when noplugins
entry is set.
您可以在MkDocs documentation中找到有关插件的更多信息。
它是如何工作的?
使用mkdocs build
或mkdocs serve
生成或提供文档时,如果一切顺利,将显示以下消息:
The PDF version of the documentation has been generated.
选项
此插件支持以下选项,以便更好地处理生成的pdf的自定义。
Option | Description |
---|---|
^{ | The author of the document. This information will be printed on the cover page of the generated PDF. |
^{ | 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 |
^{ | The table of content title. The default value is Table of Contents |
^{ | The position of the table of contents. This option supports 3 differents values: ^{ |
^{ | The file name of the generated PDF, relative to the ^{ |
^{ | Relative to your ^{ |
贡献
从报告一个bug到提交一个pull请求,每一个贡献都是值得赞赏和欢迎的。使用Github issues报告错误、提问和请求功能。
感谢
这个插件的想法是在公共部门的一个项目中提出的。经过多次研究,我找到了一些插件,引导我找到当前的解决方案。他们给了我很多灵感,非常感谢:
- Terry Zhao作者MkDocs PDF Export Plugin我们灵感的源泉。我们在这个项目中使用了他的一些代码。
- Kozea team将WeasyPrint作为一个开源项目提供给我们。生成的pdf的默认设计基于他们的工作report Sample。
- Martin Donath作者Material for MkDocs,他的一些css文件被用来设计adminion、codehilite、arthmatex、emoji等的布局。