开始使用

用 npx 运行 Knap。CLI 要求 Node.js 20 或更高版本。

npx knap render -t '# {{ title }}' --set title=Hello

这会打印 # Hello。要渲染文件，请提供模板以及一个包含其变量的 JSON 对象：

npx knap render template.md --data data.json --output note.md

CLI 与库 API 包含在同一个包中。它启用标准过滤器。依赖 DOM 的 HTML 过滤器和自定义应用集成通过库 API 提供。

安装

日常使用时，全局安装 Knap：

npm install -g knap
knap render template.md --data data.json --output note.md

你也可以用 npm install knap 把 Knap 安装到项目中，再用 npx knap 或通过 npm 脚本运行。

语言帮助

无需离开终端，也无需网络连接即可探索这门语言：

knap help syntax
knap help filters
knap help filter date
knap help tags
knap help tag for

knap help filters 会列出 CLI 中每个过滤器及其别名和简短说明。knap help tags 会列出逻辑标签。各个过滤器和标签页面会显示语法、参数、示例和预期输出。示例字符串使用 JSON 引号，因此换行和空白都是显式的。

过滤器帮助与网站文档目录共用同一份清单。它只列出 CLI 中可用的过滤器；依赖 DOM 的 HTML 过滤器需要库 API。knap --help 会链接到这些命令，模板错误中也会包含相关的帮助命令。

校验

在提供数据之前先检查模板：

knap validate template.md
knap validate -t '{{ title | upper }}'
cat template.md | knap validate

校验会检查模板语法、过滤器名称，以及可静态检查的过滤器参数。它不会渲染模板、不会检查变量是否存在、不会检查运行时取值，也不会对动态过滤器参数求值。要检查运行时行为，请用真实数据渲染。

选择一种模板来源：文件、--template（-t）或 stdin。省略模板参数，或用 - 表示管道输入。不接受数据、输出和批量选项。不会写入任何文件。

成功时以状态码 0 退出；出错时以状态码 1 退出。诊断信息和成功消息写入 stderr；stdout 保持为空。用 knap validate --help 查看用法。

模板

把模板文件作为 render 之后的参数传入，或用 --template（-t）提供内联模板：

knap render template.md --data data.json
knap render -t '{{ title | upper }}' --set title=Hello

要从 stdin 读取模板，请用 - 或省略模板参数：

cat template.md | knap render - --data data.json
cat template.md | knap render --data data.json

每条命令只选择一种模板来源。

数据

对于 render，提供一个 JSON 对象。要为每条记录生成一个文件，请使用批量渲染。

用 --data（-d）提供 JSON 文件，或用 --data-json 提供内联 JSON 对象：

knap render template.md --data data.json
knap render -t '{{ title }}' --data-json '{"title":"Hello"}'

对象的属性会成为模板变量。嵌套对象、数组、数字、布尔值和 null 都保留各自的类型。数据必须是 JSON 对象；不提供数据时，变量默认为 {}。

用 --set 添加或覆盖单个变量：

knap render template.md --data data.json --set title="Custom title"
knap render -t '{{ First name }}' --set 'First name=Ada'

--set 可以重复使用。无论参数顺序如何，覆盖都在 JSON 数据之后应用，同一个键最后出现的覆盖生效。取值始终是字符串，因此 --set enabled=false 提供的是文本 false，而不是布尔值。键就是字面的顶层名称：--set a.b=hi 定义的是键 a.b，可用 {{ a.b }} 解析，而不是创建名为 a 的对象。要提供嵌套对象或其他取值类型，请使用 JSON。

在 --data 和 --data-json 之间选择其一作为基础数据来源。

要把数组渲染到单个文件中，请把它包在具名变量下（如 {"articles": [...]}），并在模板中使用循环。要让每个数组项生成一个文件，请使用 batch。

管道

用 --data - 从另一条命令读取 JSON：

cat data.json | knap render template.md --data -

只能有一个输入使用 stdin。通过管道传入数据时，请显式提供模板文件或 --template。

来自 Defuddle

Defuddle 会从网页中提取内容和元数据。把它的 JSON 输出通过管道传给 Knap，即可用你的模板格式化结果：

npx defuddle parse https://example.com/article --markdown --json \
  | npx knap render template.md --data - --output note.md

把示例 URL 替换为你要提取的文章。模板可以直接引用 Defuddle JSON 输出中的属性：

# {{ title }}

{{ content }}

输出

渲染后的文本默认写入 stdout，且不额外添加换行。用 --output（-o）写入文件，或用 shell 重定向 stdout：

knap render template.md --data data.json --output note.md
knap render template.md --data data.json > note.md

--output - 显式选择 stdout。输出文件在渲染成功后创建或覆盖；缺失的父目录会自动创建。

错误与警告

诊断信息写入 stderr。模板错误包含其代码、来源、行和列。参数、输入、渲染和文件系统错误以状态码 1 退出。渲染失败不产生输出，并让传给 --output 的文件保持不变。shell 重定向遵循你的 shell 行为，可能在 Knap 运行前就截断目标文件。

非致命警告允许渲染成功，并以状态码 0 退出。

批量渲染

用 batch 从一个模板创建多个文件：

knap batch template.md --data articles.csv --output-dir notes \
  --filename '{{ title | safe_name }}.md'

数据来源

来源	每条输出对应	模板变量
CSV 文件	行	列标题成为变量名；取值保持为字符串。
JSON 数组文件	对象	对象的属性，保留其类型。
JSON 文件夹	文件	每个文件 JSON 对象的属性。

knap batch template.md --data articles.json --output-dir notes
knap batch template.md --data ./articles --output-dir notes
cat articles.json | knap batch template.md --data - --output-dir notes

对于内联数据，请对对象组成的 JSON 数组使用 --data-json。通过管道传入的数据默认是 JSON 数组。要传入 CSV，请使用 --format csv：

cat articles.csv | knap batch template.md --data - --format csv --output-dir notes

和 render 一样，单条命令中只有模板或数据能读取 stdin。--template 和 --set 也适用于 batch；覆盖会应用到每条记录。

文件输入在扩展名为 .csv 时使用 CSV，否则使用 JSON。--format csv 或 --format json 会覆盖该探测结果，对没有扩展名的文件同样适用。文件夹输入和 --data-json 要求 JSON；不能对它们使用 --format csv。CSV 使用逗号作为分隔符；不支持 TSV。

第一个非空 CSV 行提供列标题。取值保持为字符串，因此像 00123 这样的标识符和像 false 这样的文本都会被保留。支持带引号的逗号、转义的双引号、内嵌换行和 UTF-8 BOM。空行会被跳过；空的或重复的标题，以及不一致的行长度都是错误。

文件夹输入按文件名顺序读取常规 .json 文件。它忽略子文件夹、符号链接和其他文件类型。文件扩展名不区分大小写。每个 JSON 文件必须包含一个对象；JSON 数组文件每个记录包含一个对象。空批次是错误。

文件名

不使用 --filename 时，文件夹输入保留每个来源的基本名，仅把 .json 改为 .md。CSV 行和 JSON 数组项则依次编号为 1.md、2.md 等。

用文件名模板根据记录取值命名文件：

knap batch template.md --data articles.json --output-dir notes \
  --filename '{{ published | date:"YYYY-MM-DD" }}-{{ title | safe_name }}.md'

文件名模板使用与内容模板相同的变量和标准过滤器。需包含所需的扩展名。结果必须是单个文件名，不含目录分隔符、控制字符或 Windows 保留字符。把数据取值插入文件名时，请使用 safe_name。

渲染后的基本名不能只由空白、点、连字符或下划线组成。像 .md 或 -.md 这样的名称会在写入任何文件之前就失败。开头的空白会被拒绝；请用 trim 或 safe_name 清理数据取值。只要剩余名称有效，可选取值可以为空，例如 {{ title }}{{ suffix }}.md。需要时请使用回退值。对于有意创建的隐藏文件，让模板以字面点开头，例如 .env 或 .{{ name }}。

预览批次

加上 --dry-run 可以校验批次并在 stdout 上逐行列出预期的输出路径，而不创建目录或写入文件：

knap batch template.md --data articles.csv --output-dir notes --dry-run

试运行会像真实运行一样执行模板、文件名、重复项和已有文件检查。用 --overwrite --dry-run 预览替换。校验失败时不打印任何路径。摘要和警告写入 stderr。预览成功并不保证之后的写入一定成功；权限、可用空间或文件都可能变化。

已有文件与错误

--output-dir 是必需的，缺失时会自动创建。已有文件会导致错误，除非传入 --overwrite：

knap batch template.md --data articles.csv --output-dir notes --overwrite

Knap 会在写入任何文件之前校验整个批次的输入、文件名和渲染内容。批次内重复的输出名称一律失败，包括仅大小写或 Unicode 规范化不同的名称。目录和符号链接不能被覆盖。

警告和完成摘要写入 stderr。除用 --dry-run 列出路径外，stdout 保持为空。出错时以状态码 1 退出。写入过程中的文件系统故障可能留下部分已写入的文件；错误中会报告完成了多少个。批次数据和准备好的输出都保存在内存中。

渲染选项

knap render [template-file] [options]

选项	简写	用途
[template-file]		模板文件，或用 - 表示 stdin。省略时，会读取管道传入的模板，除非提供了 --template。
--template <text>	-t	内联模板。
--data <file>	-d	JSON 变量文件，或用 - 表示 stdin。
--data-json <json>		内联 JSON 变量对象。
--set <key=value>		用字符串覆盖一个顶层变量；可重复。
--output <file>	-o	输出文件，或用 - 表示 stdout（默认）。
--help	-h	显示帮助。
--version	-v	显示包版本。

批量选项

knap batch [template-file] --data <source> --output-dir <dir> [options]

选项	简写	用途
[template-file]		模板文件，或用 - 表示 stdin。省略时，会读取管道传入的模板，除非提供了 --template。
--template <text>	-t	内联模板。
--data <source>	-d	CSV 文件、JSON 数组文件、JSON 文件夹，或用 - 表示 stdin（默认 JSON）。
--data-json <json>		替代 --data 的内联 JSON 数组。
--format <csv|json>		覆盖文件格式探测，或指定 stdin 的格式。
--set <key=value>		用字符串覆盖每条记录中的一个顶层变量；可重复。
--output-dir <dir>		必需的目标目录；缺失时自动创建。
--filename <template>		针对每条记录求值的文件名模板。
--overwrite		允许替换已有的常规文件。
--dry-run		校验并列出输出路径，而不创建目录或写入文件。
--help	-h	显示帮助。
--version	-v	显示包版本。