当前位置：首页 > article >正文

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

article 2025/1/9 12:34:15

文章目录

1. 背景
2. 插件 makrdown Preview Enhanced 使用
3. 工具 wkhtmltopdf
4. Markdown 转带目录的 PDF
5. 生成的 PDF 可以更加美化
- 5.1 vscode Markdown Preview Enhanced 自定义 CSS
- 5.2 使用更多的 wkhtmltopdf 参数
6. 总结

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 使用

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

3. 工具 wkhtmltopdf

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

4. Markdown 转带目录的 PDF

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

ctrl +shift + p 调处菜单，搜索 Markdown Preview Enhanced 选择 Customize CSS

根据自己的设计，设计 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

其中