如何将 Markdown 转换为 PDF

Markdown非常适合写作:语法清晰,易于阅读,到处都能用。但当您需要与不使用Markdown的人(大多数人)分享文档时,PDF是通用格式。基于浏览器的Markdown到PDF转换器在本地处理整个工作,无需将您的内容上传到任何服务器。

为什么将Markdown转换为PDF

• 共享文档:PDF在每个设备上看起来都一样。Markdown文件需要渲染器。
• 打印:Markdown没有页面大小或边距的概念。PDF正确处理打印布局。
• 专业外观:具有适当标题样式、边距和分页符的PDF看起来比原始Markdown文件更精致。
• 提交:许多工作场所、学校和客户期望PDF格式。
• 归档:PDF/A是ISO标准化的长期存储格式。Markdown不是。
• 电子邮件附件:PDF在每个电子邮件客户端中可靠地渲染。Markdown在大多数中显示为原始文本。
• 法律和审计跟踪:已签署的PDF在大多数司法管辖区被认可;Markdown文件不被认可。

如何将Markdown转换为PDF

1. 粘贴您的Markdown:在编辑器中输入或粘贴您的内容。右面板显示其外观的实时预览。
2. 自定义页面设置:选择页面大小(A4、Letter、A3、A5)并调整边距以满足您的需要。
3. 生成并下载:点击「生成PDF」创建文档,然后立即下载。

Markdown的简史

Markdown由John Gruber于2004年创建,Aaron Swartz提供了重要意见。Gruber的目标是一种写作友好的语法,可以按原样阅读并渲染为HTML,取代大多数人不得不直接编写的混乱HTML。原始规范是有意最小化的:标题、粗体、斜体、链接、列表、引用、代码。

该格式风靡一时。到2010年,Stack Overflow、GitHub、Reddit和大多数面向开发者的网站都采用了Markdown。CommonMark(2014)标准化了语法以修复Gruber原始规范中的歧义。GitHub Flavored Markdown(GFM)添加了表格、任务列表、删除线和原始Markdown所缺乏的其他功能。

今天,Markdown是技术写作的通用语:GitHub上的README文件、文档站点(Docusaurus、MkDocs、VuePress)、博客(Hugo、Jekyll、Eleventy、Astro)、笔记应用(Obsidian、Notion、Bear)和聊天工具(Discord、Slack、Element)。人类可读源和可靠的HTML/PDF渲染的组合是它没有被任何更新的东西取代的原因。

Markdown语法快速参考

您可以创建什么

• 技术文档:API参考、内部维基页面、运行手册、作为交付物打印的项目README
• 报告和案例研究:带有嵌入代码块、表格和图表的研究
• 简历和CV:导出为专业PDF的清晰文本驱动格式
• 学术论文和笔记:讲座笔记、学习指南、章节草稿
• 商业文档:会议纪要、提案、流程变更文档
• 书籍和电子书:许多作者用Markdown起草长篇内容,并将其导出为PDF进行审阅
• 食谱、学习指南、日志:任何结构重要但您不想与文字处理器作斗争的事情

Markdown风味

不同的解析器实现了略有不同的Markdown规则:

• CommonMark:标准化核心。标题、粗体、斜体、链接、列表、代码块、引用块。
• GitHub Flavored Markdown(GFM):添加表格、任务列表、删除线、自动链接、原始HTML支持。最广泛部署的风味。
• MultiMarkdown / Pandoc Markdown:添加脚注、引用、数学(LaTeX样式)、定义列表、元数据块。用于学术和书籍上下文。
• AsciiDoc:具有更多功能(警告、包含、条件内容)的单独格式。语法不同;不是Markdown但经常被比较。
• MDX:用于React组件的Markdown + JSX。仅Web;不能干净地渲染为PDF。

大多数基于浏览器的Markdown到PDF转换器使用GFM或CommonMark。如果您使用脚注/引用语法编写,请在生成前验证您的转换器是否支持它。

样式化输出

Markdown是纯文本;PDF需要样式决策:

• 字体选择:大多数转换器默认对正文使用无衬线字体(Helvetica、Arial),对代码使用等宽字体(Courier、Menlo)。一些允许自定义字体选择。
• 代码高亮:代码块中的语法高亮(使用Prism.js或highlight.js等库)使代码更易读。如果您的文档有很多代码,请启用此功能。
• 表格样式:默认表格很简单。一些转换器提供条纹行或边框以提高清晰度。
• 标题层次结构:H1应该是您的文档标题(每个文档一个);H2用于主要部分;H3-H6用于子部分。跳过级别(H1 → H4)会混淆屏幕阅读器和目录生成器。
• 页边距:文档的标准是20-25mm边距。海报和密集布局为15mm。低于10mm的边距看起来很拥挤。

常见陷阱

• 代码块溢出页面:非常长的行换行或被切断。要么打破长行,要么使用较小的代码字体。
• 图像不出现:外部图像必须位于可访问的URL。使用base64数据URI(![alt](data:image/png;base64,iVBOR...))或相对路径,如果您的转换器支持它们。
• 表格跨页面分隔:长表格可能在行中间分隔。大多数转换器无法自动插入「重复标题」。变通方法:手动将表格分成更小的表格。
• 硬编码的换行符未保留:Markdown中的单个换行符不是换行符;您需要两个尾随空格或一个空行。这是「我的段落被压缩在一起」问题的常见来源。
• 标题未编号:Markdown不自动编号标题。如果您的文档需要「1.1.1」风格的编号,您必须手动添加或使用支持计数器的转换器。
• 数学公式不渲染:标准Markdown不包括数学。如果您写$E = mc^2$期望LaTeX渲染,您需要一个支持KaTeX或MathJax的转换器。
• URL中的特殊字符:图像文件名中的空格除非URL编码(my%20image.png而不是my image.png),否则会中断引用。

需要考虑的替代方案

• 浏览器打印到PDF:在浏览器中打开渲染的Markdown(任何预览工具),Ctrl/Cmd+P,另存为PDF。免费、即时,但样式有限。
• Pandoc:用于在Markdown、PDF、DOCX、EPUB、LaTeX之间转换的命令行工作马。更多功能(引用、模板、数学),但需要安装。
• Typora:付费桌面Markdown编辑器,具有高质量PDF导出。最适合每天编写Markdown。
• Marp:用于演示的Markdown。导出为PDF作为幻灯片。
• Eleventy/Hugo/Jekyll + PDF插件:用于希望自动生成其文章PDF版本的静态站点作者。

对于一次性文档和大多数创作,基于浏览器的转换器最快。对于写作工作流程中的重复使用,值得设置Pandoc或Typora。

提示

• 生成前预览:检查实时预览,确保创建PDF前标题、列表和代码块看起来正确。
• 使用标题作为结构:标题在PDF中创建清晰的文档层次结构。使用#作为标题,##作为节,###作为子节。
• 添加分页符:如果您需要强制新页面,可以使用内联HTML:<div style="page-break-after: always"></div>。
• 保持代码块简短:非常长的代码块可能会溢出PDF中的页面宽度。如果需要,将其分成较小的块。
• 使用A4和Letter进行测试:如果您的文档可能在不同国家打印,请检查它在A4(国际使用)和US Letter(北美使用)上都看起来不错。
• 使用Markdown linter:像markdownlint这样的工具可以捕获格式不一致(尾随空格、混合列表标记),这些在PDF中显示为视觉故障。作为CLI工具或VS Code扩展免费提供。
• 匹配平台的风味:如果您的受众在GitHub上阅读,使用GFM功能(任务列表、表格)。如果您通过Pandoc发布,可以使用脚注和引用。

隐私和机密文件

Markdown到PDF转换器完全在您的浏览器中运行。您粘贴的Markdown源、生成的HTML预览和最终PDF都保留在您的设备上。没有任何东西被上传到服务器、记录或与任何人共享。

这很重要,因为Markdown文档通常包含机密内容:NDA下的技术规范、内部文档、未发表写作的草稿、带有个人观察的研究笔记、技术格式的财务报告。云Markdown到PDF服务按设计将您的内容发送到他们的服务器。一些保留输入用于「改进」或分析。对于敏感的Markdown内容,基于浏览器的转换器是更安全的选择。

基于浏览器的转换在页面加载后也可以离线工作,这在旅行或在飞机上工作时很有用。