make-pdf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nutrient Make PDF

Turn a Markdown or HTML file into a finished PDF through the Nutrient DWS Build API. The differentiator over local

chromium --print-to-pdf

or Pandoc is the output stage: the same call can emit tagged, accessible PDF/UA or archival PDF/A, and stamp a diagonal text watermark — compliance work a plain HTML-to-PDF pipeline cannot do.

通过Nutrient DWS Build API将Markdown或HTML文件转换为成品PDF。与本地

chromium --print-to-pdf

或Pandoc相比，其差异化优势在于输出阶段：同一调用即可生成带标签的无障碍PDF/UA或归档PDF/A，还可添加斜向文本水印——这些合规性工作是普通HTML转PDF流程无法实现的。

Quick Start

快速开始

All paths below are relative to this skill's directory (the directory containing

scripts/

and

assets/

Export the API key before generating (not needed for
```
--html-only
```
or the smoke test):
- ```
export NUTRIENT_API_KEY="nutr_sk_..."
```
  (the same variable the sibling
```
document-processor-api
```
  scripts use;
```
NUTRIENT_DWS_API_KEY
```
  is accepted as a fallback)
Generate:

bash

uv run scripts/make-pdf.py --input report.md --out report.pdf

The

markdown-it-py

and

nutrient-dws

packages are fetched automatically on first use.

以下所有路径均相对于本skill的目录（包含

scripts/

和

assets/

的目录）。

生成前需导出API密钥（使用
```
--html-only
```
或冒烟测试时无需此步骤）：
- ```
export NUTRIENT_API_KEY="nutr_sk_..."
```
  （与同级
```
document-processor-api
```
  脚本使用相同的变量；
```
NUTRIENT_DWS_API_KEY
```
  可作为备选）
生成PDF：

bash

uv run scripts/make-pdf.py --input report.md --out report.pdf

首次使用时会自动获取

markdown-it-py

和

nutrient-dws

包。

Common Tasks

常见任务

Standard PDF from Markdown:

uv run scripts/make-pdf.py --input notes.md --out notes.pdf

Accessible PDF/UA (tagged, for WCAG/ADA/EAA requirements): add
```
--accessible
```
Archival PDF/A: add
```
--pdfa
```
(conformance via
```
--pdfa-level
```
, one of
```
pdfa-1a/1b/2a/2b/2u/3a/3u
```
, default
```
pdfa-2b
```
; only valid together with
```
--pdfa
```
)
Draft watermark: add
```
--watermark DRAFT
```
Memo layout instead of the default document layout:
```
--template memo
```
Dark theme:
```
--theme dark
```
Title-page metadata:
```
--title
```
,
```
--subtitle
```
,
```
--author
```
,
```
--date
```
(or set them in Markdown frontmatter; CLI flags win)
Inspect the rendered HTML without calling the API (offline, no key):
```
--html-only
```
(Markdown input only — errors on
```
.html
```
input, which already is the HTML)
Debug layout alongside the PDF:
```
--output-html
```
writes the intermediate HTML next to the PDF
Batch: point
```
--input
```
at a directory (with
```
--out <dir>
```
, required) to convert every
```
.md
```
/
```
.html
```
in it — see Batch Conversion below

--accessible

and

--pdfa

are mutually exclusive (one output type per build). Check exact arguments with

uv run scripts/make-pdf.py --help

从Markdown生成标准PDF：

uv run scripts/make-pdf.py --input notes.md --out notes.pdf

无障碍PDF/UA（带标签，满足WCAG/ADA/EAA要求）：添加
```
--accessible
```
参数
归档PDF/A：添加
```
--pdfa
```
参数（通过
```
--pdfa-level
```
指定合规等级，可选值为
```
pdfa-1a/1b/2a/2b/2u/3a/3u
```
，默认值为
```
pdfa-2b
```
；仅当同时使用
```
--pdfa
```
时有效）
添加草稿水印：添加
```
--watermark DRAFT
```
参数
使用备忘录布局替代默认文档布局：
```
--template memo
```
深色主题：
```
--theme dark
```
标题页元数据：
```
--title
```
、
```
--subtitle
```
、
```
--author
```
、
```
--date
```
（也可在Markdown前置元数据中设置；CLI参数优先级更高）
仅查看渲染后的HTML而不调用API（离线模式，无需密钥）：
```
--html-only
```
（仅支持Markdown输入——若输入为
```
.html
```
文件会报错，因为其本身已是HTML）
调试布局并同时输出PDF：
```
--output-html
```
会在PDF旁写入中间HTML文件
批量转换：将
```
--input
```
指向目录（需配合
```
--out <dir>
```
参数），转换目录中所有
```
.md
```
/
```
.html
```
文件——详见下方批量转换部分

--accessible

和

--pdfa

参数互斥（每次构建仅能生成一种输出类型）。可通过

uv run scripts/make-pdf.py --help

查看完整参数说明。

Input Rules

输入规则

```
.md
```
input is converted to HTML with a CommonMark+GFM parser (tables, strikethrough, task lists), then wrapped in the selected template with the theme CSS inlined — one self-contained HTML file is uploaded.
```
.html
```
input is uploaded as-is; template, theme, and metadata flags do not apply and a warning names any that were passed. Use it when you already have styled HTML.
YAML frontmatter in Markdown (
```
title
```
,
```
subtitle
```
,
```
author
```
,
```
date
```
,
```
template
```
,
```
theme
```
) controls the cover block; CLI flags override frontmatter. When no title is given anywhere, the first
```
#
```
heading (or the filename) becomes the document title, so accessible output always has a real title.
External images require network fetches on the DWS side and referenced local images are not uploaded in v1 — embed images as
```
data:
```
URIs if they must appear.

```
.md
```
输入会通过CommonMark+GFM解析器转换为HTML（支持表格、删除线、任务列表），然后用所选模板包裹并内联主题CSS——最终上传一个独立的HTML文件。
```
.html
```
输入会直接上传；模板、主题和元数据参数不适用，若传入此类参数会发出警告。当您已有样式化HTML时可使用此方式。
Markdown中的YAML前置元数据（
```
title
```
、
```
subtitle
```
、
```
author
```
、
```
date
```
、
```
template
```
、
```
theme
```
）控制封面块；CLI参数会覆盖前置元数据。若未在任何地方指定标题，则第一个
```
#
```
标题（或文件名）会成为文档标题，确保无障碍输出始终包含真实标题。
外部图片需要DWS端进行网络请求，而v1版本中不会上传本地引用的图片——若图片必须显示，请将其嵌入为
```
data:
```
URI格式。

Verification (built in)

内置验证功能

Compliance outputs are verified, not just labeled. With

--accessible

--pdfa

, the generated PDF is automatically checked after the build (

--no-verify

opts out); exit code 3 means "generated but failed verification" — the PDF is kept on disk so you can inspect it. If the verifier itself cannot run, the build still exits 3 rather than silently passing;

--no-verify

is the explicit way to accept unverified output. Passing

--verify

without a compliance flag is rejected up front — a standard PDF has no conformance claim to check.

Two assurance levels, and be honest about which one ran:

Structural checks (always available, via
```
scripts/verify-pdf.py
```
): the PDF/UA-1 claim marker (
```
pdfuaid
```
XMP part 1 — PDF/UA-2 documents are out of scope), tagged-structure signals (
```
MarkInfo
```
,
```
StructTreeRoot
```
), language,
```
DisplayDocTitle
```
, and a non-empty document title — or the PDF/A identification (
```
pdfaid
```
part + conformance, matched against the requested level). These catch real failures but are not a full conformance audit.
Full audit (optional): if
```
verapdf
```
is installed on PATH, the verifier also runs veraPDF for a genuine conformance validation and reports its verdict. Recommend installing veraPDF when the user's requirement is regulatory (ADA/EAA deadlines, records retention).

The verifier also works standalone on any PDF, including ones this skill did not create:

bash

uv run scripts/verify-pdf.py --input existing.pdf --profile pdfua
uv run scripts/verify-pdf.py --input archive-dir/ --profile pdfa --pdfa-level pdfa-2b

合规输出会经过验证，而非仅添加标签。使用

--accessible

或

--pdfa

参数时，生成的PDF会在构建后自动进行检查（可通过

--no-verify

参数跳过）；退出码3表示“已生成但验证失败”——PDF会保留在磁盘上供您检查。若验证器本身无法运行，构建仍会返回退出码3而非静默通过；

--no-verify

是接受未验证输出的明确方式。若未指定合规参数却传递

--verify

，会直接被拒绝——标准PDF无合规性声明可检查。

提供两种保证级别，请如实说明使用了哪一种：

结构检查（始终可用，通过
```
scripts/verify-pdf.py
```
）：检查PDF/UA-1声明标记（
```
pdfuaid
```
XMP第1部分——暂不支持PDF/UA-2文档）、标签结构信号（
```
MarkInfo
```
、
```
StructTreeRoot
```
）、语言、
```
DisplayDocTitle
```
以及非空文档标题——或检查PDF/A标识（
```
pdfaid
```
部分+合规等级，与请求的等级匹配）。这些检查可发现实际问题，但并非完整的合规性审计。
完整审计（可选）：若PATH中安装了
```
verapdf
```
，验证器还会运行veraPDF进行真正的合规性验证并报告结果。当用户需求涉及法规要求（如ADA/EAA截止日期、记录保留）时，建议安装veraPDF。

验证器也可独立用于任何PDF，包括非本skill生成的PDF：

bash

uv run scripts/verify-pdf.py --input existing.pdf --profile pdfua
uv run scripts/verify-pdf.py --input archive-dir/ --profile pdfa --pdfa-level pdfa-2b

Batch Conversion

批量转换

--input <directory>

converts every

.md

.markdown

.html

, and

.htm

file directly in that directory (non-recursive), up to 4 concurrently:

bash

uv run scripts/make-pdf.py --input reports/ --out pdfs/ --accessible

```
--out <dir>
```
is required for directory input; outputs are named
```
<stem>.pdf
```
.
Per-document metadata comes from each file's frontmatter, first
```
#
```
heading, or filename — global
```
--title
```
/
```
--subtitle
```
are rejected for directory input. Shared flags (
```
--template
```
,
```
--theme
```
,
```
--author
```
,
```
--date
```
,
```
--watermark
```
, compliance and verify flags) apply to every file.
Failures don't stop the batch: a summary on stderr lists converted/verified/failed counts, stdout still prints only created file paths. Exit 0 = all good, 1 = at least one build failed, 3 = builds succeeded but at least one verification failed.
Batch mode never overwrites existing outputs (and refuses inputs that would collide on the same output name) — point
```
--out
```
at a fresh directory or remove stale files when regenerating.

--input <directory>

会转换目录中直接包含的所有

.md

、

.markdown

、

.html

和

.htm

文件（非递归），最多同时处理4个文件：

bash

uv run scripts/make-pdf.py --input reports/ --out pdfs/ --accessible

目录输入时必须指定
```
--out <dir>
```
参数；输出文件命名为
```
<stem>.pdf
```
。
每个文档的元数据来自各自文件的前置元数据、第一个
```
#
```
标题或文件名——目录输入时不接受全局
```
--title
```
/
```
--subtitle
```
参数。共享参数（
```
--template
```
、
```
--theme
```
、
```
--author
```
、
```
--date
```
、
```
--watermark
```
、合规与验证参数）适用于所有文件。
单个文件失败不会终止批量处理：stderr会输出转换/验证/失败数量的摘要，stdout仅打印已创建的文件路径。退出码0表示全部成功，1表示至少一个构建失败，3表示构建成功但至少一个验证失败。
批量模式永远不会覆盖现有输出（且会拒绝可能导致输出文件名冲突的输入）——重新生成时请将
```
--out
```
指向新目录或删除旧文件。

Layout Honesty (Chromium limits)

布局限制说明（Chromium局限）

DWS renders HTML with headless Chromium (

printToPDF

). That means standard print CSS works (

@page

size and margins,

page-break-*

break-*

rules,

@media print

), but CSS Paged Media features Chromium does not implement will silently not render:

position: running()

running headers/footers,

counter(page)

, and

target-counter()

TOC page numbers. Do not promise page-numbered TOCs or running headers from CSS. If the user needs those, say so and offer the trade-offs (front-matter TOC without page numbers, or a different toolchain).

DWS使用无头Chromium的

printToPDF

渲染HTML。这意味着标准打印CSS可正常工作（

@page

尺寸和边距、

page-break-*

break-*

规则、

@media print

），但Chromium未实现的CSS分页媒体功能不会生效：

position: running()

运行页眉/页脚、

counter(page)

、

target-counter()

目录页码。请勿承诺通过CSS生成带页码的目录或运行页眉。若用户需要这些功能，请说明情况并提供替代方案（不带页码的前置目录，或使用其他工具链）。

Chaining Other Document Operations

与其他文档操作联动

Generation is one step. Related operations live in sibling plugins from the same marketplace:

Sign, redact, or merge the produced PDF: the

document-processor-api

skill —

/plugin install nutrient-dws@nutrient-skills

. Its scripts read the same

NUTRIENT_API_KEY

; run them from that skill's own directory, e.g.

uv run scripts/sign.py --input report.pdf --out report-signed.pdf

Make an EXISTING PDF accessible (auto-tag for PDF/UA): the
```
remediate-pdf
```
skill —
```
/plugin install remediate-pdf@nutrient-skills
```
. This skill generates new PDFs; that one fixes old ones (and bundles the same
```
verify-pdf.py
```
).

生成只是一个步骤。相关操作可使用同一市场中的同级插件：

对生成的PDF进行签名、编辑或合并：使用

document-processor-api

skill——

/plugin install nutrient-dws@nutrient-skills

。其脚本使用相同的

NUTRIENT_API_KEY

；请在该skill的目录中运行，例如

uv run scripts/sign.py --input report.pdf --out report-signed.pdf

。

使现有PDF具备无障碍功能（自动添加PDF/UA标签）：使用
```
remediate-pdf
```
skill——
```
/plugin install remediate-pdf@nutrient-skills
```
。本skill用于生成新PDF；该skill用于修复旧PDF（并包含相同的
```
verify-pdf.py
```
）。

Implementation Rules

实现规则

Fail fast with a clear message when
```
NUTRIENT_API_KEY
```
(or the
```
NUTRIENT_DWS_API_KEY
```
fallback) is missing (unless
```
--html-only
```
).
Never log the API key or request headers.
Write outputs to explicit paths and print each created file path (one path per line on stdout; progress on stderr). A debug HTML path prints as soon as the file exists, even if a later build step fails.
Non-zero exit on any failure; do not claim success unless the output file exists and is non-empty.

当
```
NUTRIENT_API_KEY
```
（或备选
```
NUTRIENT_DWS_API_KEY
```
）缺失时，立即终止并给出明确提示（使用
```
--html-only
```
时除外）。
绝不记录API密钥或请求头。
将输出写入指定路径，并打印每个已创建文件的路径（stdout每行打印一个路径；进度信息输出至stderr）。即使后续构建步骤失败，调试HTML路径也会在文件创建后立即打印。
任何失败均返回非零退出码；仅当输出文件存在且非空时才视为成功。

Validation

验证

Before calling this skill done after changes:

```
uv run scripts/smoke-test.py
```
— offline (no network, no key): every template x theme combination, Markdown feature survival (headings, tables, code blocks), verifier checks against constructed fixtures, and batch discovery.
Generate one real PDF if a key is available; for compliance outputs let the built-in verification run (or run
```
verify-pdf.py
```
explicitly) rather than only checking the file is non-empty.

修改完成后，需完成以下验证才能确认本skill可用：

```
uv run scripts/smoke-test.py
```
——离线模式（无需网络和密钥）：测试所有模板与主题的组合、Markdown特性保留情况（标题、表格、代码块）、验证器对构造测试用例的检查，以及批量文件发现功能。
若有可用密钥，生成一个真实PDF；对于合规输出，需运行内置验证（或显式运行
```
verify-pdf.py
```
），而非仅检查文件非空。