knap

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 を使用してください。

1 つのテンプレートソース（ファイル、-t、または標準入力）と 1 つのデータソース（--data または --data-json）を選択してください。標準入力を読み取れる入力は 1 つだけです。テンプレートファイルまたは -t がない場合、Knap は標準入力からテンプレートを読み取ります。

出力はデフォルトで標準出力になります。-o は親ディレクトリを作成し、レンダリングが成功した後に出力先を上書きします。エラーはステータス 1 で終了します。診断情報は標準エラー出力に送られます。警告は成功した出力に付随する場合があります。

テンプレート

値には {{ variable }}、フィルターには |、ロジックには {% ... %} を使用します。たとえば、これを template.md として保存します:

---
{{ title | yaml_property:"title" }}
{{ tags | yaml_property:"tags" }}
---
# {{ title | trim }}
{% if author %}
By {{ author }}
{% endif %}

{{ content }}

完全な frontmatter プロパティには yaml_property を使用して、値が正しく引用およびインデントされるようにします。CLI には標準フィルターが含まれていますが、Web Clipper のブラウザ変数、セレクター、プロンプト、または DOM に依存する HTML フィルターは提供されません。変数は JSON を通じて指定してください。

レンダリング前にテンプレートを確認します:

knap validate template.md

検証では、データやファイル出力なしで、構文、フィルター名、および静的なフィルター引数をチェックします。変数の存在、実行時の値、または動的な引数はチェックしません。実行時の動作を確認するには、実際のデータでレンダリングしてください。診断情報は標準エラー出力に送られ、関連するヘルプコマンドが含まれます。

Defuddle パイプライン

Web ページを Markdown コンテンツを含む JSON として抽出し、それをノートにレンダリングします:

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

title や content などの Defuddle の JSON プロパティは、直接テンプレート変数になります。

バッチレンダリング

CSV の行、JSON 配列のオブジェクト、またはフォルダー内の JSON ファイルごとに 1 つのファイルを作成します:

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

配列には --data articles.json を、JSON オブジェクトのフォルダーには --data ./articles を使用します。CSV ヘッダーは変数名になり、値は文字列のままです。パイプされたデータはデフォルトで JSON になります。パイプされた CSV には --format csv を追加してください。

--dry-run を使用すると、ファイルを書き込まずに出力パスを検証および一覧表示できます。既存のファイルには --overwrite が必要です。ドライラン中も同様です。バッチ内で出力名が重複すると、--overwrite を指定していてもエラーになります。

ファイル名テンプレートは、ディレクトリを含まない、拡張子付きの単一のファイル名を生成する必要があります。データから生成される名前には safe_name を使用してください。--filename がない場合、Knap はソース JSON のベース名を保持するか、CSV の行と配列の項目に 1.md、2.md などの番号を付けます。