MkDocs-with-PDF 使用教程

1. 项目介绍

MkDocs-with-PDF 是一个用于 MkDocs 的插件，旨在从 MkDocs 仓库生成单一的 PDF 文件。该插件受到 MkDocs PDF Export Plugin 的启发，提供了生成带有封面和目录的 PDF 文件的功能。它能够自动为标题编号，并支持子页面标题级别的调整。

主要功能

• 生成带有封面和目录的 PDF 文件。
• 自动为标题（h1-h3）编号。
• 支持子页面标题级别的调整。
• 使用 WeasyPrint 进行 PDF 生成。

适用场景

• 需要将 MkDocs 文档导出为 PDF 格式的项目。
• 希望在 PDF 中集成封面和目录的项目。

2. 项目快速启动

安装

首先，确保你已经安装了 MkDocs 和 Python 3.6 或更高版本。然后，使用 pip 安装 mkdocs-with-pdf 插件：

pip install mkdocs-with-pdf

配置

在 mkdocs.yml 文件中启用插件：

plugins:
  - with-pdf

生成 PDF

运行以下命令生成 PDF 文件：

mkdocs build

生成完成后，你将在 pdf 目录下找到生成的 PDF 文件。

3. 应用案例和最佳实践

案例一：项目文档导出

假设你有一个 MkDocs 项目，包含多个文档页面。使用 mkdocs-with-pdf 插件，你可以轻松地将所有文档导出为一个 PDF 文件，方便用户离线阅读。

案例二：集成封面和目录

在某些情况下，你可能希望生成的 PDF 文件包含封面和目录，以便更好地组织文档内容。通过配置插件选项，你可以自定义封面和目录的标题，甚至添加自定义的封面图片。

最佳实践

• 自定义封面和目录：通过配置 cover_title 和 toc_title 选项，自定义封面和目录的标题。
• 排除特定页面：使用 exclude_pages 选项排除不需要包含在 PDF 中的页面。
• 调整标题级别：通过 heading_shift 选项调整子页面标题的级别，使其更符合文档结构。

4. 典型生态项目

MkDocs

MkDocs 是一个快速、简单且美观的静态站点生成器，专为项目文档设计。它使用 Markdown 编写文档，并生成静态 HTML 站点。

WeasyPrint

WeasyPrint 是一个用于将 HTML 和 CSS 转换为 PDF 的库。mkdocs-with-pdf 插件依赖于 WeasyPrint 来生成 PDF 文件。

MkDocs Material

MkDocs Material 是一个流行的 MkDocs 主题，提供了丰富的功能和美观的界面。mkdocs-with-pdf 插件可以与 MkDocs Material 主题无缝集成，生成高质量的 PDF 文档。

通过结合这些工具，你可以创建一个完整的文档生成和导出解决方案，满足各种项目的需求。