VSCode原生不支持带书签PDF导出，必须依赖Prince或Pandoc等外部工具链；Markdown PDF插件因底层用wkhtmltopdf/Puppeteer仅做静态渲染，无法解析标题语义生成PDF原生书签。
VSCode 本身不支持一键导出带书签的 PDF，所有“带书签”能力都依赖外部工具链；原生插件（如 Markdown PDF）默认不生成书签，必须换用 Prince 或 Pandoc 才能真正支持结构化目录。
为什么 Markdown PDF 插件导出的 PDF 没有书签
Markdown PDF（作者 yzane）底层调用 wkhtmltopdf 或 Puppeteer 渲染 HTML 后转 PDF，但这两个工具默认不解析标题层级、不生成 PDF 书签（Outline）。即使 Markdown 里写了 ## 章节名，导出后 PDF 文件属性里 Outline 项为空——这不是配置遗漏，是工具链能力缺失。
- 它只做静态渲染快照，不分析文档语义结构
- 尝试在
markdown-pdf.css里加@page { }或 JavaScript 注入无效，因为导出阶段 JS 不执行 - 部分用户误以为开启
markdown-pdf.toc就能出书签，其实该选项仅控制是否在页面顶部插入 HTML 格式的目录（非 PDF 原生书签），点击无法跳转
用 Prince 实现真·PDF 书签：需手动安装并配置
Prince 是目前 VSCode 生态中唯一开箱即用支持自动生成 PDF 书签的工具。它会自动将 h1–h6 映射为 PDF Outline 条目，并支持 CSS 控制层级、标题样式和页眉页脚。
通过 jina.ai 将网页抓取为精简的 markdown，用于在需要获取 URL 并获取压缩的 markdown 内容以节省 token。触发词 l...
- 先从 princexml.com/download 下载对应系统版本，安装完成后终端运行
prince --version验证 - 在 VSCode 设置中搜索
markdown-preview-enhanced.princePath，填入完整路径，例如：/Applications/Prince.app/Contents/MacOS/prince（macOS）或C:\Program Files\Prince\engine\bin\prince.exe（Windows） - 确保 Markdown 文件开头有合法 YAML front matter，至少包含
title字段，否则 Prince 可能跳过书签生成 - 导出时右键预览窗口 →
Markdown Preview Enhanced: Export to PDF (via Prince)，生成的 PDF 在 Adobe Acrobat 或 Preview 中打开后，左侧书签面板自动展开且可点击跳转
用 Pandoc + LaTeX 替代方案：更可控但安装重
如果你需要页码、章节编号、交叉引用或中文字体精确控制，Pandoc 配合 XeLaTeX 是更可靠的选择，它生成的 PDF 书签由 LaTeX 的 hyperref 和 bookmark 宏包驱动，稳定性高于前端渲染链路。
- 先装 Pandoc：
brew install pandoc（macOS）、scoop install pandoc（Windows） - 再装完整 LaTeX 发行版：
brew install --cask mactex（macOS）或texlive-full（Ubuntu），确保xelatex --version可执行 - 在 Markdown 文件顶部添加 YAML front matter，显式启用书签：
--- toc: true toc-depth: 3 geometry: margin=1in mainfont: "Noto Serif CJK SC" ---
- 导出命令示例：
pandoc readme.md -o readme.pdf --pdf-engine=xelatex；VSCode 中可通过tasks.json封装为快捷任务
别踩这些坑：书签失效的常见原因
即使工具选对了，书签仍可能为空或层级错乱，问题往往不在 Markdown 写法本身。
- 标题行前面有多余空格或制表符，导致 Pandoc/Prince 无法识别为标题节点
- 用了
### 标题 {#custom-id}这类自定义锚点，但没在 YAML 中配toc: true，Prince 默认忽略 ID 属性 - VSCode 工作区启用了 Remote-SSH，但 Prince 或 LaTeX 只装在本地；远端服务器必须也装好对应工具+中文字体（如 Ubuntu 装
fonts-wqy-zenhei） - 导出前未保存文件，或文件名含中文/空格/特殊符号（如
第1章.md），部分工具会静默失败
真正决定书签质量的是工具链对文档结构的理解深度，而不是 CSS 或插件开关。Prince 和 Pandoc 是目前仅有的两个能在 VSCode 环境下稳定产出可点击、可折叠、层级准确的 PDF 原生书签的方案。其他所谓“一键带书签”宣传，基本都混淆了 HTML 目录和 PDF Outline 的本质区别。
