用 Knap CLI 把模板与 JSON/CSV…

当需要套用 Knap 模板、把 JSON 或 CSV 数据批量转成 Markdown 文件，或把 Defuddle 抓取的网页内容格式化成笔记时使用。

适用场景

解决思路

1. 安装 Knap：运行 `npm install -g knap`（需要 Node.js 20 或更高版本），或改用 `npx knap`。
2. 运行 `knap --help` 查看可用命令和选项；通过离线参考了解语言：`knap help syntax`、`knap help filters`、`knap help filter date`、`knap help tags`、`knap help tag for`，先用列表找到名称，再查看单项帮助获取语法、参数和带预期输出的示例。
3. 用 JSON 变量渲染模板：`knap render template.md --data article.json -o note.md`。
4. 内联提供模板和数据：`knap render -t '# {{ title | trim }}' --data-json '{"title":"Hello"}'`。
5. 覆盖变量或通过管道传入 JSON 数据：`knap render template.md --data article.json --set 'title=Custom title'`，或 `cat article.json | knap render template.md --data -`。
6. 数据必须是 JSON 对象，其属性会成为模板变量；`--set` 用字符串覆盖顶层字面量键；嵌套对象、数组、数字和布尔值请使用 JSON。
7. 模板来源（文件、`-t` 或 stdin）只能选一个，数据来源（`--data` 或 `--data-json`）也只能选一个；只能有一个输入读取 stdin；没有模板文件或 `-t` 时，Knap 从 stdin 读取模板。
8. 输出默认到 stdout；`-o` 会在渲染成功后创建父目录并覆盖目标文件；错误以状态码 1 退出，诊断信息输出到 stderr，警告可能伴随成功输出一起出现。
9. 在模板中使用 `{{ variable }}` 表示值、`|` 表示过滤器、`{% ... %}` 表示逻辑；例如把 frontmatter 写成 `{{ title | yaml_property:"title" }}` 和 `{{ tags | yaml_property:"tags" }}`，正文用 `# {{ title | trim }}`、`{% if author %}By {{ author }}{% endif %}` 和 `{{ content }}`。
10. 对完整的 frontmatter 属性使用 `yaml_property`，以保证值被正确加引号和缩进；CLI 自带标准过滤器，但不提供 Web Clipper 的浏览器变量、选择器、提示词或依赖 DOM 的 HTML 过滤器，变量需通过 JSON 提供。
11. 渲染前用 `knap validate template.md` 检查模板：它检查语法、过滤器名称和静态过滤器参数，不需要数据也不产生文件输出；它不检查变量是否存在、运行时值或动态参数，需用真实数据渲染来验证运行时行为；诊断信息输出到 stderr 并包含相关帮助命令。
12. Defuddle 流水线：用 `defuddle parse https://example.com/article --md --json | knap render template.md --data - -o note.md` 把网页提取为带 Markdown 内容的 JSON 再渲染成笔记；Defuddle 的 JSON 属性（如 `title` 和 `content`）会直接成为模板变量。
13. 批量渲染：为 CSV 每一行、JSON 数组每个对象或文件夹中每个 JSON 文件生成一个文件，例如 `knap batch template.md --data articles.csv --output-dir notes --filename '{{ title | safe_name }}.md'`。
14. 批量数据来源：`--data articles.json` 表示数组，`--data ./articles` 表示文件夹中的 JSON 对象；CSV 表头成为变量名，值保持字符串；管道数据默认按 JSON 解析，管道传入 CSV 时加 `--format csv`。
15. 用 `--dry-run` 校验并列出输出路径而不写文件；已存在的文件需要 `--overwrite`，dry run 期间也一样；批次内输出名重复即使有 `--overwrite` 也算错误。
16. 文件名模板必须生成带扩展名的单个文件名，不能包含目录；数据派生的名称请使用 `safe_name`；不指定 `--filename` 时，Knap 保留源 JSON 的文件名，或把 CSV 行和数组项编号为 `1.md`、`2.md` 等。

适用边界 · 注意事项

• 需要 Web Clipper 的浏览器变量、选择器、提示词或依赖 DOM 的 HTML 过滤器时，Knap CLI 不提供这些，需自行通过 JSON 提供变量。
• 只想检查变量是否存在或运行时值是否正确时，`knap validate` 不覆盖这些，必须用真实数据渲染验证。