【DocFX文档翻译】演练3: 生成PDF文档
演练3: 生成PDF文档
完成了演练2: 为文档网站添加API文档 后，我们成功地创建了一个包含概念和API文档的网站。 在本节中，我们将为这些文章生成PDF文件。
完成了演练2以后, 我们的 D:\docfx_walkthrough\docfx_project 文件夹应该是如下结构(在 这里 下载代码 ):
|- articles
|- images
|- src
|- src2
|- index.md
|- toc.yml
|- docfx.json
第0步. 安装必备环境
我们需要 wkhtmltopdf 来生成 PDF. 下载 wkhtmltopdf 到本地目录, 例如. E:\Program Files\wkhtmltopdf\, 使用命令 set PATH=%PATH%;E:\Program Files\wkhtmltopdf\bin 将执行文件目录添加 %PATH% 环境变量。
[!注意]
另外你可以使用 chocolatey 的命令choco install wkhtmltopdf直接安装wkhtmltopdf。这个操作在安装过程中会自动添加执行目录到 %PATH% 环境变量。
第1步. 添加 toc.yml 指定 PDF生成
目前的设计是每个TOC文件生成一个对应的PDF文件，TOC也被用作PDF的封面，所以我们在 pdf文件夹下面为pdf生成创建一个特定的toc.yml文件，使用TOC 包含 来包含其他TOC文件的内容。
- name: Articles
href: ../articles/toc.yml
- name: Api Documentation
href: ../api/toc.yml
- name: Another Api Documentation
href: ../api-vb/toc.yml
第1步. docfx.json 文件中添加 pdf 配置节
参数类似 build 配置节, 区别是使用不同的模板（内置模板是pdf.default），以及不同的输出路径。 每个TOC文件生成PDF文件时，我们也排除了TOC文件。
...
"pdf": {
"content": [
{
"files": [
"api/**.yml",
"api-vb/**.yml"
],
"exclude": [
"**/toc.yml",
"**/toc.md"
]
},
{
"files": [
"articles/**.md",
"articles/**/toc.yml",
"toc.yml",
"*.md",
"pdf/*"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site_pdf/**",
"**/toc.yml",
"**/toc.md"
]
},
{
"files": "pdf/toc.yml"
}
],
"resource": [
{
"files": [
"images/**"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site_pdf/**"
]
}
],
"overwrite": [
{
"files": [
"apidoc/**.md"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site_pdf/**"
]
}
],
"dest": "_site_pdf"
}
好了, 让我们运行 docfx，你会在 _site_pdf 目录发现生成了 walkthrough3_pdf.pdf pdf文件：
PDF Preview
总结
在本演练中，我们根据 pdf 文件夹下的TOC文件构建一个PDF文件。 请注意，TOC在PDF生成中起着重要作用，它不仅可以指定PDF中包含的文件，还可以指定此PDF文件的封面。 一个TOC文件生成一个PDF文件，所以不要忘记从docfx.json中排除不需要的TOC文件。
