MDPDF - Markdown到PDF的转换器

一个命令行Markdown到PDF的转换器，支持页眉、页脚和自定义样式表。Mdpdf拥有非常可配置的功能，并提供了一个JavaScript API供更高级用途使用。

有关如何使用页眉和页脚的示例，请参见示例目录。

如果您使用 Atom 文本编辑器, 请查看 markdown-pdf 插件,它使用了 mdpdf。

赞助这个项目

该项目在业余时间维护。如果您或您的公司觉得它很有用,请考虑通过赞助来支持该项目。

贡献

如果您想报告错误或贡献修复和新功能,请查看贡献者指南。

安装

全局安装以便通过命令行使用。

npm install mdpdf -g

本地安装以使用API。

npm install mdpdf --save

使用示例

• mdpdf README.md - 使用GitHub Markdown CSS和一些额外的基础样式进行简单转换。
• mdpdf README.md --style styles.css --header header.hbs --h-height 22 - 使用自定义样式转换,并设置22毫米高的页眉。

选项

• --style=<filename> - 您想应用于PDF的单个CSS样式表
• --header=<filename> - 要注入到PDF页眉的HTML (.html)文件
• --h-height=<height> - 页眉部分的高度
• --footer=<filename> - 要注入到PDF页脚的HTML (.html)文件
• --f-height=<height> - 页脚部分的高度
• --border=<size> - 所有边(上、左、下、右)的边框大小(默认:20mm)
• --border-top=<size> - 顶部边框(默认:20mm)
• --border-left=<size> - 左边框(默认:20mm)
• --border-bottom=<size> - 底部边框(默认:20mm)
• --border-right=<size> - 右边框(默认:20mm)
• --gh-style - 当使用 --style 时启用默认的gh-styles
• --no-emoji - 禁用表情符号转换
• --debug - 保存生成的HTML以进行调试
• --help - 显示此菜单
• --version - 显示应用程序版本
• --format=<format> - PDF大小格式:A3、A4、A5、Legal、Letter、Tabloid(默认:A4)
• --orientation=<orientation> - PDF方向:纵向或横向(默认:纵向)

长度参数(<height>和<size>)需要一个单位。有效单位为mm、cm、in和px。

页眉和页脚

Mdpdf由Puppeteer驱动,Puppeteer是谷歌的无头Chrome浏览器项目。Puppeteer提供了一些可用于插入诸如页码之类内容的页眉和页脚HTML类。

注意: mdpdf 2.x之前使用的是Phantom.js,它对页眉和页脚的支持要好得多,并且对它们的样式支持更好。不幸的是,Phantom.js不再受支持,并且有一些其他的渲染错误,这意味着不再可能将其作为mdpdf的核心组件支持。如果您之前依赖良好的页眉和页脚支持,您可能希望坚持使用1.x版本,直到Puppeteer优先考虑更好的页眉和页脚支持。目前,2.x+版本中的页眉和页脚确实可以工作,但它们的样式必须通过--styles选项和一些CSS标签独立于主Markdown文件来处理,这些标签确实无法正常工作。除此之外,2.x+版本的页眉和页脚应该没有任何问题。

环境变量

• MDPDF_STYLES - 当从命令行调用mdpdf时,如果未指定--style,则使用此环境变量指定的样式表的完整路径。

表情符号支持

文本中的表情符号也受支持,但有一些快捷方式不起作用,需要使用长版本,例如:+1:不起作用,但:thumbsup:可以。

编程API

API非常简单,只有一个convert()函数,它接受一些选项。该convert方法使用Promise。有关完整示例,请参见bin/index.js!

API使用示例

const mdpdf = require('mdpdf');
const path = require('path');

let options = {
    source: path.join(__dirname, 'README.md'),
    destination: path.join(__dirname, 'output.pdf'),
    styles: path.join(__dirname, 'md-styles.css'),
    pdf: {
        format: 'A4',
        orientation: 'portrait'
    }
};

mdpdf.convert(options).then((pdfPath) => {
    console.log('PDF Path:', pdfPath);
}).catch((err) => {
    console.error(err);
});

选项

• source (required) - 源Markdown文件的完整路径。
• destination (required) - 目标(PDF)文件的完整路径。
• styles - 应用于PDF的单个CSS样式表的完整路径。
• ghStyle - 是否使用GitHub Markdown CSS的布尔值,默认为false。
• defaultStyle - 是否使用额外的默认样式的布尔值。这些样式提供了一些基本的边框和字体大小。默认为false。
• header - 包含您的页眉的Handlebars(.hbs)文件的完整路径。如果设置此项,您必须设置页眉高度(见下文)。
• debug - 可选的路径,可以设置为使中间HTML保存到所需的路径。
• pdf (required) - 一个包含一些子参数的对象,用于控制最终的PDF文档
  • format (required) - 最终文档格式,允许值为"A3、A4、A5、Legal、Letter、Tabloid"
  • orientation - 最终文档大小方向,允许值为"portrait、orientation"
  • header - 一个包含一些页眉设置的子对象
    • height - 文档页眉的高度,单位为mm(默认45mm)。如果要使用页眉,则必须设置此项。
  • border - 文档边框

Docker使用

要构建mdpdf的Docker镜像,请使用以下命令:

docker build -t mdpdf .

要在Docker容器中运行mdpdf,可以使用以下命令。这个示例将当前目录挂载到容器内的/app目录,并将example.md转换为example.pdf:

docker run --rm -v $(pwd):/app mdpdf example.md

这样您就可以在不需要在主机上安装Node.js或任何依赖项的情况下使用mdpdf,只需要安装Docker即可。