如何用MDPDF打造专业PDF文档？10个实用命令行参数详解
项目地址: https://gitcode.com/gh_mirrors/md/mdpdf MDPDF是一款功能强大的Markdown转PDF命令行工具，能够帮助开发者快速将Markdown文档转换为专业级PDF文件。这款工具支持自定义样式表、页眉页脚、多种页面格式等高级功能，是文档生成和报告制作的利器。无论是技术文档、项目报告还是个人笔记，MDPDF都能轻松应对。
🚀 快速入门：安装与基本使用
首先，通过npm全局安装MDPDF：
npm install mdpdf -g
最简单的转换命令只需指定Markdown文件：
mdpdf README.md
这条命令会生成一个名为README.pdf的文件，使用GitHub风格的Markdown样式和基本排版。
📋 10个实用命令行参数详解
1. 自定义样式表（--style）
为PDF添加自定义CSS样式，打造个性化文档外观：
mdpdf README.md --style=custom.css
这个参数允许你完全控制PDF的视觉效果，包括字体、颜色、间距等所有样式属性。
2. 添加页眉（--header）
为PDF文档添加专业页眉，适合公司文档或正式报告：
mdpdf README.md --header=header.html --h-height=25mm
页眉文件需要是HTML格式，可以使用examples/headers/header.html作为参考模板。
3. 添加页脚（--footer）
添加页码、版权信息等页脚内容：
mdpdf README.md --footer=footer.html --f-height=20mm
页脚同样支持HTML格式，可以包含动态内容如页码、日期等。
4. 页面边框控制（--border）
精确控制PDF页面的边距，支持单独设置四个方向：
mdpdf README.md --border=15mm
# 或分别设置
mdpdf README.md --border-top=20mm --border-left=15mm --border-bottom=25mm --border-right=15mm
支持的单位包括mm、cm、in和px。
5. 页面格式与方向（--format, --orientation）
选择不同的纸张大小和页面方向：
# A4纵向（默认）
mdpdf README.md --format=A4 --orientation=portrait
# A3横向
mdpdf README.md --format=A3 --orientation=landscape
# 信纸尺寸
mdpdf README.md --format=Letter
支持的格式：A3、A4、A5、Legal、Letter、Tabloid。
6. 文档标题设置（--title）
为PDF设置元数据标题，影响PDF查看器中的显示：
mdpdf README.md --title="项目技术文档"
这个标题会出现在PDF查看器的标题栏和书签中。
7. GitHub样式保留（--gh-style）
即使使用自定义样式，也保留GitHub Markdown的基础样式：
mdpdf README.md --style=custom.css --gh-style
这样既能自定义样式，又能保持GitHub Markdown的良好可读性。
8. 禁用表情符号（--no-emoji）
关闭Markdown中的表情符号转换：
mdpdf README.md --no-emoji
对于不需要表情符号的正式文档非常有用。
9. 调试模式（--debug）
保存生成的HTML中间文件，便于调试样式问题：
mdpdf README.md --debug
生成的HTML文件会保存在与源文件同名的.html文件中。
10. 超时设置（--timeout）
设置渲染超时时间，处理复杂文档：
mdpdf README.md --timeout=60000
默认超时为30秒（30000毫秒），复杂文档可能需要更长时间。
🎯 高级使用技巧
组合使用多个参数
MDPDF支持同时使用多个参数，创建高度定制化的PDF：
mdpdf README.md \
--style=company.css \
--header=header.html --h-height=25mm \
--footer=footer.html --f-height=20mm \
--format=A4 --orientation=portrait \
--border=20mm \
--title="季度技术报告"
环境变量设置
通过环境变量设置全局默认样式表：
export MDPDF_STYLES=/path/to/default.css
mdpdf README.md # 自动使用默认样式
程序化API调用
除了命令行，MDPDF还提供JavaScript API，适合集成到其他工具中：
const mdpdf = require('mdpdf');
const options = {
source: 'README.md',
destination: 'output.pdf',
styles: 'custom.css',
pdf: {
format: 'A4',
orientation: 'portrait'
}
};
mdpdf.convert(options).then(pdfPath => {
console.log('PDF创建成功:', pdfPath);
});
🔧 实用示例场景
技术文档生成
mdpdf technical-doc.md \
--style=tech-doc.css \
--header=tech-header.html --h-height=30mm \
--footer=tech-footer.html --f-height=25mm \
--format=A4 \
--title="API技术文档"
会议报告制作
mdpdf meeting-notes.md \
--style=report.css \
--border=25mm \
--format=Letter \
--orientation=landscape \
--title="项目进度报告"
个人笔记整理
mdpdf daily-notes.md \
--style=notes.css \
--no-emoji \
--format=A5 \
--border=15mm
💡 最佳实践建议
- 样式表设计：参考src/assets/default.css了解默认样式结构
- 页眉页脚模板：查看examples/目录中的示例文件
- 批量处理：结合shell脚本批量转换多个Markdown文件
- 版本控制：将样式文件和模板纳入版本控制，确保一致性
- 测试验证：使用
--debug参数检查HTML中间结果，确保样式正确应用
🚨 常见问题解决
问题：页眉页脚样式不生效 解决方案：确保页眉页脚的CSS样式独立于主文档样式，因为Puppeteer对页眉页脚的样式支持有限。
问题：转换速度慢 解决方案：减少文档中的图片数量，或增加--timeout参数值。
问题：样式冲突 解决方案：使用--debug参数检查生成的HTML，逐步调试样式问题。
MDPDF作为一款强大的Markdown转PDF工具，通过灵活的命令行参数提供了丰富的定制能力。无论是简单的文档转换还是复杂的报告生成，都能满足不同场景的需求。掌握这些参数的使用方法，你将能够轻松创建专业级的PDF文档！✨
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
