# @cenk1cenk2/md-printer 中文文档

规范地址：https://npmcn.com/package/%40cenk1cenk2/md-printer/

版本：3\.2\.20
npm 元数据更新时间：2026-11-04T11:29:48.975Z
中文译文更新时间：2026-11-09T07:37:15.944Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cenk1cenk2/md-printer
原文对照：https://npmcn.com/package/%40cenk1cenk2/md-printer/?lang=original
项目主页：https://gitlab.kilic.dev/utils/md-printer
源码仓库：https://gitlab.kilic.dev/utils/md-printer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：158 kB，79 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.15\.0
- 运行依赖：54 个
- 首次发布：2021-11-14T19:18:11.510Z
- 最新版本发布：2026-11-04T11:29:48.883Z
- 近 30 天下载量：3975（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：216（近 12 个月 71 个）

## 中文简介

通过斯维尔特模板将Render markdown 或 Yaml 输入 PDF 或 HTML 并配有 Puppeteer .

## 安装

```sh
npm install @cenk1cenk2/md-printer
```

也可以使用：`pnpm add @cenk1cenk2/md-printer`、`yarn add @cenk1cenk2/md-printer`、`bun add @cenk1cenk2/md-printer`

## README

# md 打印器

通过 Svelte 模板将 Markdown 或 YAML 文件变成 PDF 或 HTML 文档。 PDF由本地安装的Chromium浏览器打印出,因此没有捆绑的Chrome下载.

## 安装

```sh
npm i -g @cenk1cenk2/md-printer
```

### 所需资源

-   节点.js >= 24.15.
-   基于铬的浏览器. md-打印机的使用 `puppeteer-core` 永远不要下载.

浏览器可执行文件按此顺序解决:

1.  `--browser <path>`。如果此路径无法执行,则 md-printer 将失败,而不是掉回.
2.  `PUPPETEER_EXECUTABLE_PATH`
3.  `CHROME_PATH`
4.  勇敢克洛姆克洛姆克洛姆克洛姆克洛姆克洛姆克洛姆克洛姆克洛德克洛德克洛德克洛德克洛德克洛德克洛德克洛德克洛德克 `PATH`。仅支持 Linux .

当运行为根或当 `CI` 设置环境变量, 浏览器以 `--no-sandbox`,因为Chromium拒绝启动它的沙盒作为根,这是CI容器中的默认.

## 使用量

```sh
# render to document.pdf in the current directory
md-printer document.md

# choose the output file
md-printer document.md out/document.pdf

# write to stdout, logs go to stderr
md-printer document.md -O > document.pdf

# read from stdin, the only argument is then the output
cat document.md | md-printer --stdin out.pdf

# template by built-in name or by path to a template directory
md-printer document.md -t kilic.dev
md-printer document.md -t ./my-template

# language for template translations
md-printer invoice.yaml -t invoice -l de

# one single page without page breaks
md-printer document.md --continuous

# HTML output instead of PDF
md-printer document.md -F html
```

-   从扩展中检测到输入类型( E)`.md`, (中文(简体) ), `.yaml`, (中文(简体) ), `.yml`和标记下 Stdin。 用它来代替它 `-f, --input-filetype`。 。 。 .
-   YAML 输入没有正文,整个文档是 `data` 的模板。 发票用这个.
-   输出默认为 `<input name>.<pdf|html>` 在当前目录中。 没有输入文件(stdin)没有默认,通过输出参数, `dest` 前题或 `-O`。 。 。 .
-   输出在原子上被写入:旁边的临时文件被重新命名为正位,保留了已有文件的模式和所有者.
-   `dest` 在前置事项和输出参数中解决当前目录,而本地资产则解决输入文件目录(当前 stdin目录)的问题.
-   只装入输入目录内的文件,用于PDF和HTML。 共通链接先被跟踪,所以目录外的链接指针也没有被加载. 远程图像按原样装入.
-   HTML 输出本地图像作为数据 URI: 图像属性(`src`, (中文(简体) ), `srcset`, (中文(简体) ), `poster`, (中文(简体) ), `style` 属性和 `<style>` 块。 文本和代码样本从未被重写.
-   `-T, --title` 设置文档标题,参见 [优先级](https://npmcn.com/package/%40cenk1cenk2/md-printer/#readme-precedence)。 。 。 .

## 标记

标记为 [统一](https://unifiedjs.com/): GitHub flavored markdown (表格,任务列表,脚注,自动链接),标题 ids,语法加亮与所选的加亮. js 主题和原始 HTML 也进行了解析,所以用 HTML 书写的标题或代码块也会得到其ID并突出显示.

`::pagebreak` 在自己的线路上开始一个新的页面。 它在任何地方工作,同样在弹性或网格布局内部,在连续模式下,每个部分都成为自己高度的一页. `<div class="page-break"></div>` 在 HTML 中和 `PageBreak` 构成部分`::page-break`)作同为相.

### 构成部分

将 Svelte 组件标记为 [指令](https://github.com/remarkjs/remark-directive)模板的组件和 [共享组件](https://npmcn.com/package/%40cenk1cenk2/md-printer/#readme-shared-components) 由kebab案的档案名称提供, `PaymentInfo.svelte` 作为 `payment-info`数字 :

```md
::payment-info{iban="AT00 0000" due="14"}

:::callout{type="warning"}
Inner markdown, **bold** included, is rendered and passed as `children`.
:::

Total :items[3 items]{count="3"} so far.
```

-   `::name{...}` 在它自己的线上是一个没有孩子的叶子部分.
-   `:::name{...}` 直至结束 `:::` 是一个容器。 其内容被渲染为下调和通过 `children` 片断.
-   `:name[label]{...}` 内部文本是内在的。 标签作为 `children`。 。 。 .
-   属性作为道具传递,始终作为字符串: `{count="3"}` 给 `count: '3'`。 。 。 . `{.note #intro flag}` 给 `class`, (中文(简体) ), `id` 财务报告和审定财务报表 `flag: ''`。 。 。 .
-   没有组件的名称保留着它写成的文字,所以 `10:30am`, (中文(简体) ), `note:here` 或者说 `::unknown` 打印时间不变.

## 前题和设置

Markdown文件取YAML前题. 对于 YAML 输入,相同的密钥是文件的顶级密钥. 所有其他密钥都以 `data`。 。 。 .

| 密钥 | 说明 |
| --- | --- |
| `template` | 内建模板名称或模板目录路径. |
| `dest` | 输出文件,相对于当前目录,而不是输入文件. |
| `outputFiletype` | `pdf` (违约)或 `html`。 。 。 . |
| `language` | 模板翻译语言. |
| `continuous` | `true` 使每个部分各有一页,每页与内容一样高,只在分页时分开. |
| `documentTitle` | 文件标题. |
| `pdfOptions` | 傀儡 [PDF 选项](https://pptr.dev/api/puppeteer.pdfoptions),在默认情况下合并. |
| `sign` | 签名选项,参见 [签名](https://npmcn.com/package/%40cenk1cenk2/md-printer/#readme-signing)。 。 。 . |

模板可携带 `settings.json` 其文档默认值 :

| 密钥 | 说明 |
| --- | --- |
| `pdfOptions` | 傀儡PDF选项. |
| `i18n` | `{ "language": "en", "fallback": "en" }`,默认和倒置的翻译语言. |
| `sign` | 签名选项. |
| `continuous` | 默认持续渲染. |
| `media` | CSS 用于打印的介质类型, `screen` (违约)或 `print`。 。 。 . |
| `highlightStyle` | 突出显示.j 主题名称来自 `highlight.js/styles`,默认为 `atom-one-dark`。 。 。 . |

默认 `pdfOptions` 为: `format: A4`, (中文(简体) ), `printBackground: true` 和比值 `30mm 40mm 30mm 20mm` (上,右,下,左). `pdfOptions` 被递归合并,所以文档可以覆盖单个密钥. `margin` 可能是 CSS 的短手字符串, 例如 `"18mm 12mm"`,而平面数字是像素,在连续模式中也是如此.

```yaml
---
template: kilic.dev
dest: ./out/report.pdf
language: de
documentTitle: Quarterly Report
pdfOptions:
  format: A4
  margin: 20mm
---
```

### 优先发言

-   常规:旗帜 > 前事 > 模板 `settings.json` > 默认值. `pdfOptions` 按默认顺序按密钥合并, `settings.json`前题.
-   语言是 `--language`,则 `language`,则 `settings.json` `i18n.language`,则 `en`。 。 。 .
-   `continuous` 当任何 `--continuous`前题或 `settings.json` 允许它.
-   文档标题是 `--title`,则 `documentTitle`,然后是 `<title>` ,然后输入文件名称.

## 发展

```sh
md-printer document.md --preview
md-printer document.md out.pdf --preview --no-open
```

-   `-p, --preview` 当输入文件、模板(组件、导入、, `settings.json`,翻译)或页面修改所使用的本地资产. 每个构建重写输出文件, 和正常运行所写的相同; 从 stdin 读取, 没有输出参数只预览 . `-O` 不被支持.
-   它启动本地预览服务器,并在被发现浏览器的应用窗口中打开,使用丢弃的配置文件. 该页面有 HTML, Split 和 PDF 标签. 构建错误,例如斯维尔特编译错误,在覆盖中显示,并由下个成功构建清除. 关闭窗口结束会话 。 Ctrl+C 在关闭浏览器、预览服务器和监视器后也结束它, 并用 130 退出; 第二 Ctrl+ C出口马上.
    -   `--host` 设置回路主机, 默认 `127.0.0.1`。 。 。 .
    -   `--port` 设置端口, 默认 `0` (放纵. 正在使用的端口以出错失败运行 .
    -   它服务于输入旁边的文件, 除了点文件, 如 `.env`。 。 。 .
    -   `--no-open` 不打开窗口: md-printer 持续重建并写入,直到 Ctrl+C,并且打印的 URL 可以手动打开.
-   预览时会跳过签名 。 运行无 `--preview` 签字.

## 模板

### 内建模板

| 名称 | 说明 |
| --- | --- |
| `default` | 与蒙特塞拉特的Markdown风格。 这是默认. |
| `kilic.dev` | 相同的样式,头部有标志,脚有标题和页码. |
| `invoice` | YAML 数据的发票(`company`, (中文(简体) ), `client`, (中文(简体) ), `payment`, (中文(简体) ), `items`, (中文(简体) ), `currency`, (中文(简体) ), `date`, (中文(简体) ), `id`和马克德笔记。 翻译 `en` 财务报告和审定财务报表 `de`,签名时的签名块。 见 `test/invoice.md`。 。 。 . |
| `mail` | 无边距的平地内容和Tailwind打字,意为 HTML 输出. |

### 正在撰写模板

模板是一个目录。 传过来 `-t ./path` 或者说 `template: ./path`。没有路径分隔符的值是一个内置名称,任何带有 `/` 或从 `.` 或者说 `~` 是一个路径.

```
my-template/
  Template.svelte   required
  settings.json     optional
  i18n/             optional, en.yaml, de.json, ...
  components/       optional, *.svelte placed from markdown, see Markdown components
```

`Template.svelte` 是一个Svelte 5组件,接收这些道具:

| Prop | 说明 |
| --- | --- |
| `data` | 前题(或YAML文件)为对象. |
| `content` | Markdown正文提供给了HTML,其指令的组成部分已经到位. YAML 输入为空 . |
| `t` | i18next 翻译函数,从 `i18n/<language>.(yaml|yml|json)`。 。 。 . |
| `language` | 决断语言. |
| `signature` | `{ date, name?, issuer?, serial? }` 在启用签名时, 否则 `undefined`。 。 。 . |

设定文档标题为 `<svelte:head><title>...</title></svelte:head>`。 。 。 .

需要 Tailwind CSS v4 或软件包导入到 `<style lang="postcss">` 块中 `Template.svelte` 或进口的任何部件。 这些块是一起收集和编译的,这样它们就可以 `@import 'tailwindcss'` 和使用情况 `@plugin`, (中文(简体) ), `@theme` 和公用事业类。 平面 `<style>` 块保留范围为斯维尔特样式. `@import` 软件包(例如 `@fontsource/*`, (中文(简体) ), `github-markdown-css`)首先从模板目录中解析,同时也从md-printer自身的依赖性解析,所以模板不需要一个 `node_modules`。选定的突出显示.js主题总是包含在内。 当地 `url()` 而图像引用则被内含为数据 URI.

图像是导入的, 将图像内含为数据 URI :

```svelte
<script>
  import logo from './logo.png'
</script>

<img src={logo} alt="logo" />
```

#### 共享组件

从 `@cenk1cenk2/md-printer/components`数字 :

| 构成部分 | 说明 |
| --- | --- |
| `Page` | 布局包装器。 儿童是身体,是 `header` 财务报告和审定财务报表 `footer` 片段是每页的打印页头和页脚. |
| `Markdown` | 将马克倒地的身体放入 `<article class="markdown-body">`,样式由 `github-markdown-css` 如果模板导入它。 指令作为活性成分. |
| `PageBreak` | 以连续模式在任何地方启动新页面。 在降级时, `::page-break` 或者说 `::pagebreak` 做同样的. |
| `PageNumber` | 目前页码,由Chrome填充. 仅收页脚. |
| `TotalPages` | 总页数,由克罗姆填充. 仅收页脚. |
| `Title` | 文件标题由Chrome填入. 仅收页脚. |
| `Date` | 印刷日期,由克罗姆填充. 仅收页脚. |
| `SignatureBlock` | 可见签名块 `signature` 道具 (英语). 需要尾风在一个 `<style lang="postcss">` 块。 可选 `labels` prop 覆盖它的文本. |

```svelte
<script>
  import { Markdown, Page, PageNumber, TotalPages, Title } from '@cenk1cenk2/md-printer/components'

  let { data } = $props()
</script>

<svelte:head>
  <title>{data.documentTitle ?? 'Document'}</title>
</svelte:head>

<Page>
  {#snippet footer()}
    <div style="width: 100%; text-align: center; font-size: 8px">
      <Title /> - <PageNumber />/<TotalPages />
    </div>
  {/snippet}

  <Markdown />
</Page>
```

#### 下沉组件

每个 `*.svelte` 模板中的文件 `components/` 目录可以从标记下放置, 参见 [构成部分](https://npmcn.com/package/%40cenk1cenk2/md-printer/#readme-components)。共享组件可以同样放置,例如 `::page-break` 或者说 `::signature-block`时,除 `Markdown`。一个与共享名称相同的模板组件取代了它.

```svelte
<!-- components/Callout.svelte -->
<script>
  import { getContext } from 'svelte'

  let { type = 'note', children } = $props()

  const { data, t, language, signature } = getContext('md-printer:document')
</script>

<aside class="callout callout-{type}">
  <strong>{t(type)}</strong>
  {@render children?.()}
</aside>
```

-   道具是指令的属性,总是字符串,和 `children` 集装箱和内含指令.
-   `getContext('md-printer:document')` 给 `{ data, t, language, signature }`,模板的道具, 所以一个组件不需要通过什么.
-   `<Markdown />` 使组件到位。 放置模板 `{@html content}` 换成他们的标记,没有范围 `<style>` 块,所以用 Tailwind 类或一个 `<style lang="postcss">` 块.
-   一个组件可以启动新页面 `PageBreak` 或带有 `page-break` 课.
-   `--preview` 抓取添加并删除组件文件 .

#### 页眉和页脚

这个 `header` 财务报告和审定财务报表 `footer` 片段被制成克罗姆的平面头和脚印,从页面中被隔离出. md-printer将CSS及其图像自动内入,包括远程图像,默认字体大小为10px. Chrome没有为他们预留空间,所以设置 `pdfOptions.margin` 内 `settings.json` 或前题大到足以让你做出什么 两者均以连续模式省略.

模板是代码: 当文档被渲染时, Svelte 组件运行在您的机器上. 只使用您信任的模板 .

## 签名

PDF输出可以通过ID奥地利,使用A-Trust以合格的电子签名签名.

```sh
md-printer invoice.yaml -t invoice --sign --sign-certificate ~/id-austria.pem
```

-   `--sign` 允许签名 . `--sign-provider` 选择提供者, `a-trust` 是唯一的和默认的. `--sign-certificate` 是您签名证书的 DER 或 PEM 文件 .
-   相同的密钥可以设置为 `sign` 前题或 `settings.json`数字 : `enabled`, (中文(简体) ), `provider`, (中文(简体) ), `certificate`, (中文(简体) ), `reason`, (中文(简体) ), `location`, (中文(简体) ), `contact`. 旗帜胜利. `reason`, (中文(简体) ), `location` 财务报告和审定财务报表 `contact` 被存储在签名中.
-   只为 PDF 输出签名并被跳过 `--preview`。 。 。 .
-   签名会话必须在您的浏览器中运行 。 md-printer在已发现浏览器的应用窗口中打开临时本地页面,使用您正常的配置文件(或带有 `xdg-open` 当找不到时, 您可以在 A- Trust 页面中登录 ID Austria, 并粘贴所产生的签名( 开始于 `MII`)回到本地页面. 剪短的贴纸在页面上被拒绝,因此可以再复制. 它等待签名到达,按 Ctrl+C 中止.
-   返回的签名在嵌入前总是被验证:其文摘必须与此文档相匹配并必须具有加密有效性. 结果被印出签名人名称,序列和发行人. 失败的校验失败运行, 并带有 `--log-level debug` 返回的签名写在输出旁边为 `<output>.cms.der`。 。 。 .
-   持有证书后,签名人名称、发行人和序列将传递到模板中作为 `signature`这样 `SignatureBlock` 可以显示谁签了名,什么时候签了名。 证书在签署时必须有效,未与该证书一起制作的回执被拒. 没有证书,只有日期.
-   验证结果于 [https://www.signaturpruefung.gv.at 互联网档案馆的存檔,存档日期2011-12-21](https://www.signaturpruefung.gv.at/)。 。 。 .

## 从 2.x 移动

-   纳尼亚克人 `template.html.j2`, (中文(简体) ), `header.html`, (中文(简体) ), `footer.html`, (中文(简体) ), `main.css` 财务报告和审定财务报表 `tailwind.css` 改为: `Template.svelte`,带有样式 `<style lang="postcss">` 块.
-   删除 `settings.json` 和前题 : `body_class`, (中文(简体) ), `css`, (中文(简体) ), `stylesheet`, (中文(简体) ), `script`, (中文(简体) ), `marked_options`, (中文(简体) ), `launch_options`, (中文(简体) ), `gray_matter_options`。 。 。 . `documentTitle` 内 `settings.json` 在模板中设置标题.
-   前题 Stdout 已消失, 使用 `-O`。 。 。 .
-   `--title` 现在胜过前题 `--template` 现在胜过前题.
-   相对于输入文件目录而不是当前目录的资产解决.
-   连续模式没有页眉和页脚.
-   `puppeteer` 改为: `puppeteer-core`,没有捆绑的 Chrome,需要基于Chrome的本地浏览器.
-   `--dev` 改为: `--preview`,它也重建并重写每个变化的输出;没有单独的 `--watch`。 。 。 .
-   默认突出显示主题为 `atom-one-dark`。 。 。 .
-   扩展名未知的文件与以前一样读作减号; `-f` 仍然强迫一种类型.
-   更新通知符和给错误打字命令的D-you-mean建议被删除,md-printer是一个单一的命令.

## 命令参考

```
Renders a markdown or yaml file through a Svelte template into a PDF or HTML document.

USAGE
  $ md-printer  [FILE] [OUTPUT] [--log-level
    silent|direct|fatal|error|warn|info|verbose|debug|trace] [-I] [-f
    md|yaml|yml] [-F pdf|html] [-O] [-t <value>] [-T <value>] [-l <value>] [-b
    <value>] [--continuous] [-p] [--host 127.0.0.1|localhost|::1] [--port
    <value>] [--open] [--sign] [--sign-provider a-trust] [--sign-certificate
    <value>]

ARGUMENTS
  [FILE]    Markdown or yaml file to render.
  [OUTPUT]  Output file. Overwrites the one defined in front-matter.

FLAGS
  -F, --output-filetype=<option>  Output file type, defaults to pdf. Overwrites
                                  the one defined in front-matter.
                                  <options: pdf|html>
  -I, --stdin                     Read the input from stdin.
  -O, --stdout                    Write the output to stdout instead of a file.
  -T, --title=<value>             Document title. Overwrites the one defined in
                                  front-matter or the template.
  -b, --browser=<value>           Browser executable used for printing.
                                  Discovered automatically when omitted (Brave,
                                  Chrome, Chromium, Edge).
  -f, --input-filetype=<option>   Input file type. Detected from the file
                                  extension, markdown for stdin and unknown
                                  extensions.
                                  <options: md|yaml|yml>
  -l, --language=<value>          Language for template translations. Overwrites
                                  the one defined in front-matter and template
                                  settings.
  -p, --preview                   Rebuild whenever the input, the template or
                                  its assets change, show the HTML and the PDF
                                  in a live preview and rewrite the output file
                                  when there is one.
  -t, --template=<value>          Built-in template name or path to a template
                                  directory, defaults to "default". Overwrites
                                  the one defined in front-matter.
      --continuous                Render the PDF as a single continuous page
                                  without page breaks.
      --host=<option>             [default: 127.0.0.1] Loopback host for the
                                  preview server, it serves the files next to
                                  the input and is never exposed to the network.
                                  <options: 127.0.0.1|localhost|::1>
      --[no-]open                 Open the preview window, --no-open keeps
                                  rebuilding and writing without one.
      --port=<value>              Port for the preview server, random when 0.
      --sign                      Sign the PDF with a qualified electronic
                                  signature through ID Austria (A-Trust).
      --sign-certificate=<value>  Signer certificate (DER or PEM) used for the
                                  visible signature block and to verify the
                                  returned signature.
      --sign-provider=<option>    Signature provider, defaults to a-trust.
                                  Overwrites the one defined in front-matter and
                                  template settings.
                                  <options: a-trust>

CLI FLAGS
  --log-level=<option>  [default: INFO, env: LOG_LEVEL] Set the log level of the
                        application.
                        <options:
                        silent|direct|fatal|error|warn|info|verbose|debug|trace>

DESCRIPTION
  Renders a markdown or yaml file through a Svelte template into a PDF or HTML
  document.
```

## 常见问题

### @cenk1cenk2/md-printer 是什么？

通过斯维尔特模板将Render markdown 或 Yaml 输入 PDF 或 HTML 并配有 Puppeteer \.

### 如何安装 @cenk1cenk2/md-printer？

在项目目录运行 npm install @cenk1cenk2/md-printer，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 md-printer，可以用 npx md-printer 直接运行。

### @cenk1cenk2/md-printer 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cenk1cenk2\_\_md-printer 是否存在。

### @cenk1cenk2/md-printer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cenk1cenk2/md-printer 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cenk1cenk2/md-printer 可以商用吗？

@cenk1cenk2/md-printer 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cenk1cenk2/md-printer 的下载量有多少？

根据 npm 官方下载统计，@cenk1cenk2/md-printer 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,975 次，日均约 133 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cenk1cenk2/md-printer 还在维护吗？

最新版本 3\.2\.20 发布于 2026/11/04（4 天前）；至今共发布 216 个版本，其中过去 12 个月发布了 71 个；首次发布于 2021/11/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。