演練3: 生成PDF文檔
完成了演練2: 為文檔網(wǎng)站添加API文檔 后秦躯，我們成功地創(chuàng)建了一個包含概念和API文檔的網(wǎng)站。 在本節(jié)中，我們將為這些文章生成PDF文件第焰。
完成了演練2以后, 我們的 D:\docfx_walkthrough\docfx_project 文件夾應(yīng)該是如下結(jié)構(gòu)(在 這里 下載代碼 ):
|- articles
|- images
|- src
|- src2
|- index.md
|- toc.yml
|- docfx.json
第0步. 安裝必備環(huán)境
我們需要 wkhtmltopdf 來生成 PDF. 下載 wkhtmltopdf 到本地目錄, 例如. E:\Program Files\wkhtmltopdf\, 使用命令 set PATH=%PATH%;E:\Program Files\wkhtmltopdf\bin 將執(zhí)行文件目錄添加 %PATH% 環(huán)境變量果录。
[!注意]
另外你可以使用 chocolatey 的命令choco install wkhtmltopdf直接安裝wkhtmltopdf上枕。這個操作在安裝過程中會自動添加執(zhí)行目錄到 %PATH% 環(huán)境變量。
第1步. 添加 toc.yml 指定 PDF生成
目前的設(shè)計是每個TOC文件生成一個對應(yīng)的PDF文件弱恒，TOC也被用作PDF的封面辨萍，所以我們在 pdf文件夾下面為pdf生成創(chuàng)建一個特定的toc.yml文件，使用TOC 包含 來包含其他TOC文件的內(nèi)容返弹。
- 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 配置節(jié)
參數(shù)類似 build 配置節(jié), 區(qū)別是使用不同的模板（內(nèi)置模板是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 目錄發(fā)現(xiàn)生成了 walkthrough3_pdf.pdf pdf文件：
總結(jié)
在本演練中默终，我們根據(jù) pdf 文件夾下的TOC文件構(gòu)建一個PDF文件椅棺。 請注意，TOC在PDF生成中起著重要作用齐蔽，它不僅可以指定PDF中包含的文件两疚，還可以指定此PDF文件的封面。 一個TOC文件生成一個PDF文件含滴，所以不要忘記從docfx.json中排除不需要的TOC文件鬼雀。
