详述 VScode &wkhtmltopdf 实现 markdown 转带目录标签(导航栏)的 PDF

1. 背景

• vscode 使用插件 makrdown Preview Enhanced，可预览 markdown 文件；

• 默认插件 makrdown Preview Enhanced 可以将 markdown 文件转为 PDF 文件以及 HTML 文件，但是 PDF 文件不带目录标签；

• 电脑权限问题，不想安装 pandoc 及其相关依赖软件；

• pandoc Linux 版本生成 PDF 有中文编码问题，安装相应中文库也会有一些字体找不到；

• wkhtmltopdf 软件可以将 HTML 文件转为 PDF 文件， 此软件有直接解压使用的包；

• wkhtmltopdf Ubuntu 版本可以正常导出 PDF 文件，但是也没有目录标签， 没有深究；

• wkhtmltopdf windows 版本导出的 PDF 文件，只显示一半，左边一侧为空白，但是有目录标签；

本文主要为了解决左侧空白的问题。

2. 插件 makrdown Preview Enhanced 使用

1. vscode 一般情况下转 PDF 使用插件 makrdown Preview Enhanced, 插件安装成功后，重启软件，右上角会有预览图标，如下图：
   
2. 点击就会在右侧出现预览界面
   
3. 在预览界面右击，会有 Export 选项
   
4. 我常用的是导处 HTML 以及 Chrome 中的 PDF, 另外三个导出 PDF 需要安装相应的软件
   
5. 不带目录标签的 PDF 导出
   
6. 此处说的目录标签是 PDF 右侧的目录栏，默认导出的 PDF 目录标签为空
   

3. 工具 wkhtmltopdf

工具在 此处 下载，可以下载安装包 Installer 或者解压的包 7z Archive, 支持 winodws 和主流 Linux 系统， 我下载的是 7z Archive 64-bit, 主要为了 HTML 转带目录的 PDF。

4. Markdown 转带目录的 PDF

1. 在 vscode 下将 Markdown 文件转为 HTML 文件;
2. 将 html 文件放在 wkhtmltox/bin 目录下, 这一步可以省略，我是没有把 bin 目录加入到系统环境变量，为了输出参数时不用绝对路径，方便一点；
3. 最关键的一步： 修改 html 文件， 将 .markdown-preview{left:50%;transform:translateX(-50%)} 删掉
   否则，wkhtmltopdf 生成的 PDF 将会显示只有一半，整体偏移了一半：
   
4. 使用 wkhtmltopdf 将 html 文件转成 pdf 文件

./wkhtmltopdf.exe --enable-local-file-access --enable-toc-back-links --disable-smart-shrinking test.html test.pdf

其中

• enable-local-file-access 是 html 是依赖于 vscode 的 css 文件，让软件可以访问这些文件
• enable-toc-back-links 允许目录跳转

生成的 PDF 最终为, 右侧带了目录标签:

5. 生成的 PDF 可以更加美化

如果你有时间，可以研究让自己生成的 PDF 更加美观，主要从两个方面。

5.1 vscode Markdown Preview Enhanced 自定义 CSS

1. ctrl +shift + p 调处菜单，搜索 Markdown Preview Enhanced 选择 Customize CSS
   
2. 根据自己的设计，设计 CSS, 如下是我的简单设计

   .markdown-preview.markdown-preview {
     // modify your style here
     // eg: background-color: blue;
     font-family: 'Georgia', serif;
     font-size: 12pt;
     line-height: 1.6;
     color: #333;
   
     h1, h2, h3, h4, h5, h6 {
       font-family: 'Arial', sans-serif;
       margin-top: 20px;
       margin-bottom: 10px;
       font-weight: bold;
     }
   
     h1 {
       font-size: 24pt;
     }
   
     h2 {
       font-size: 20pt;
     }
   
     h3 {
       font-size: 18pt;
     }
   
     h4 {
       font-size: 16pt;
     }
   
     h5 {
       font-size: 14pt;
     }
   
     h6 {
       font-size: 12pt;
     }
     
   }
   

5.2 使用更多的 wkhtmltopdf 参数

wkhtmltopdf 工具有更多的参数，我也没有太深入研究，感兴趣的可以详细研究一下，参考链接。

我使用了如下命令：

./wkhtmltopdf.exe --dpi 300 --footer-center "[page] / [topage]" --footer-font-size 8 --footer-line --footer-spacing 3 --header-spacing 3 --header-font-size 8 --header-right "[date] [time]" --enable-local-file-access --enable-toc-back-links --disable-smart-shrinking test.html test.pdf

其中

• dpi 分辨率高一点
• footer-center 页脚中间加上页码和总页码
• footer-font-size 页脚字体小一点
• footer-line 加上页脚线
• footer-spacing 页脚距离正文的距离
• header-spacing 页眉距离正文的距离
• header-font-size 页眉字体小一点
• header-right 页眉右边显示时间戳

6. 总结

主要为了解决 vscode 生成的 html 文件，wkhtmltopdf 将该 html 文件转为带目录的 pdf 文件，显示一半的问题，解决方案是删除 html 文件的部分内容，没有找到该字段在插件设置的位置。