sublime怎么实现markdown转pdf文档_sublime安装Pandoc插件教程【方案】

sublime Text 需借助已安装的 Pandoc 工具及 Pandoc Build System 插件实现 markdown 转 PDF；必须先配置 PATH 并验证 pandoc –version，再安装插件、设置构建系统，推荐用终端调试确保 xelatex 引擎与中文字体参数正确。

sublime text 本身不支持直接将 Markdown 转 PDF，必须借助外部工具 Pandoc，并通过插件桥接。核心前提是：你本地已安装 pandoc 命令行工具，否则任何插件都无效。

确认 pandoc 是否已正确安装并可用

这是最容易卡住的一步。很多用户装了 Pandoc 但没加进系统 PATH，导致 Sublime 找不到命令。

• 在终端（macOS/linux）或命令提示符（windows）中运行 pandoc --version，必须返回版本号（如 pandoc 3.1.10）
• 如果提示 'pandoc' is not recognized 或 command not found，说明未配置 PATH —— 不要跳过这步去装插件
• macOS 用户若用 Homebrew 安装，通常路径是 /opt/homebrew/bin/pandoc；Windows 用户需手动把 Pandoc 的 bin 目录（如 C:UsersXXXappDataLocalPandoc）加入系统环境变量

安装 Pandoc Build System 插件（推荐 Package Control 方式）

Sublime 上最轻量、维护良好的方案是 Pandoc Build System，不是“Pandoc”或“MarkdownPDF”这类容易过时或依赖 Phantomjs 的旧插件。

• 按下 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macos），输入 Package Control: Install Package
• 搜索并安装 Pandoc Build System（作者是 guillermooo，gitHub 仓库活跃）
• 安装后无需重启，但需手动设置构建系统：菜单栏 Tools → Build System → Pandoc
• 注意：该插件默认使用 pandoc 命令，不自带二进制，完全依赖你本地安装的版本

用快捷键一键生成 PDF（并处理中文/样式问题）

默认构建会输出 .pdf，但中文乱码、无 css 样式、目录缺失是常见结果，需调整构建参数。

• 按下 Ctrl+Shift+B（或 Cmd+Shift+B），选择 Pandoc: PDF 即可生成同名 PDF
• 若中文显示为方块，必须添加 LaTeX 引擎和字体参数 —— 在 Sublime 中打开 Tools → Build System → New Build System…，填入：

{     "cmd": ["pandoc", "$file", "-o", "$file_base_name.pdf", "--pdf-engine=xelatex", "-V", "mainfont=PingFang SC", "--toc", "--toc-depth=3"],     "selector": "source.gfm",     "path": "/opt/homebrew/bin"  // macOS 示例；Windows 改为你的 pandoc 所在目录，如 "C:\Users\XXX\AppData\Local\Pandoc" }

• --pdf-engine=xelatex 是关键，支持 Unicode 和系统字体；-V mainfont=... 指定中文字体（macOS 用 PingFang SC，Windows 可试 SimSun 或 microsoft YaHei）
• 保存为 Pandoc-ZH.sublime-build，之后在构建系统列表里就能选它

替代方案：不用插件，直接用终端调用 pandoc（更可控）

当插件行为异常（比如构建卡住、不报错也不出文件），直接甩开插件，用终端执行是最可靠的排障方式。

• 确保当前目录是 Markdown 文件所在路径，运行：

pandoc README.md -o output.pdf --pdf-engine=xelatex -V mainfont="PingFang SC" --toc

• 这样能立刻看到完整错误输出（比如缺少 xeCJK 宏包、字体找不到），比插件隐藏的错误信息有用得多
• 一旦终端能成功生成，再回头检查 Sublime 的 path 或构建参数 —— 90% 的“插件不工作”本质是路径或引擎配置偏差

真正麻烦的从来不是插件装不上，而是 Pandoc 的 PDF 输出链路太长：Markdown → AST → LaTeX → xelatex → PDF。中间任一环（字体、宏包、引擎路径）没对齐，就静默失败。建议先跑通终端命令，再套进 Sublime。