knap 是做什麼的？
使用 Knap CLI 以變數、篩選器與邏輯渲染 Markdown 模板。
若未安裝：npm install -g knap（需要 Node.js 20 或更新版本）。亦可使用 npx knap。
執行 knap --help 查看可用指令與選項。透過 CLI 的離線參考來探索語言：
knap help syntax
knap help filters
knap help filter date
knap help tags
knap help tag for
使用列表查詢名稱，然後針對個別語法、參數及預期輸出範例請求個別說明。
用法
使用 JSON 變數渲染模板：
knap render template.md --data article.json -o note.md
直接提供模板與資料：
knap render -t '# {{ title | trim }}' --data-json '{"title":"Hello"}'
覆蓋變數或透過管道傳遞 JSON 資料：
knap render template.md --data article.json --set 'title=Custom title'
cat article.json | knap render template.md --data -
資料必須是 JSON 物件；其屬性會成為模板變數。--set 會以字串覆蓋文字層級的鍵。巢狀物件、陣列、數字與布林值請使用 JSON。
選擇一個模板來源（檔案、-t 或 stdin）與一個資料來源（--data 或 --data-json）。只有一個輸入可以讀取 stdin。若沒有模板檔案或 -t，Knap 會從 stdin 讀取模板。
輸出預設為 stdout。-o 會在渲染成功後建立父目錄並覆寫目標檔案。錯誤時退出碼為 1；診斷訊息輸出至 stderr。警告可能在輸出成功時伴隨出現。
模板
使用 {{ variable }} 代表值，| 代表篩選器，{% ... %} 代表邏輯。例如，將以下內容儲存為 template.md：
---
{{ title | yaml_property:"title" }}
{{ tags | yaml_property:"tags" }}
---
# {{ title | trim }}
{% if author %}
By {{ author }}
{% endif %}
{{ content }}
使用 yaml_property 來處理完整的 frontmatter 屬性，確保值被正確引號與縮排。CLI 包含標準篩選器，但不提供 Web Clipper 瀏覽器變數、選擇器、提示詞或依賴 DOM 的 HTML 篩選器。請透過 JSON 提供變數。
在渲染前檢查模板：
knap validate template.md
驗證會檢查語法、篩選器名稱及靜態篩選器引數，不需要資料或檔案輸出。它不會檢查變數是否存在、執行時期值或動態引數；請使用真實資料進行渲染以檢查執行時期行為。診斷訊息會輸出至 stderr，並包含相關的說明指令。
Defuddle 管線
將網頁提取為包含 Markdown 內容的 JSON，再渲染成筆記：
defuddle parse https://example.com/article --md --json \
| knap render template.md --data - -o note.md
Defuddle 的 JSON 屬性（例如 title 與 content）會直接成為模板變數。
批次渲染
為 CSV 每一行、JSON 陣列中每個物件或資料夾中每個 JSON 檔案各建立一個檔案：
knap batch template.md --data articles.csv --output-dir notes \
--filename '{{ title | safe_name }}.md'
使用 --data articles.json 處理陣列，或使用 --data ./articles 處理資料夾中的 JSON 物件。CSV 標題會成為變數名稱，值保持為字串。管線資料預設為 JSON；對於管線 CSV 請加上 --format csv。
使用 --dry-run 來驗證並列出輸出路徑，但不實際寫入檔案。現有檔案需要 --overwrite，包括在試執行期間。批次中重複的輸出名稱即使使用 --overwrite 也會視為錯誤。
檔名模板必須產出單一檔案名稱及其副檔名，不可包含目錄。資料衍生的名稱請使用 safe_name。若未使用 --filename，Knap 會保留來源 JSON 的基礎名稱，或將 CSV 行與陣列項目標記為 1.md、2.md 等。