Knap

Utilisez Knap CLI pour rendre des templates Markdown avec des variables, des filtres et de la logique.

Si non installé : npm install -g knap (nécessite Node.js 20 ou version ultérieure). Sinon, utilisez npx knap.

Exécutez knap --help pour consulter les commandes et options disponibles. Découvrez le langage via la référence hors ligne du CLI :

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

Utilisez les listes pour trouver les noms, puis demandez l'aide individuelle pour la syntaxe, les paramètres et les exemples avec résultats attendus.

Usage

Rendre un template avec des variables JSON :

knap render template.md --data article.json -o note.md

Fournir un template et des données en ligne :

knap render -t '# {{ title | trim }}' --data-json '{"title":"Hello"}'

Surcharger une variable ou envoyer des données JSON en pipe :

knap render template.md --data article.json --set 'title=Custom title'
cat article.json | knap render template.md --data -

Les données doivent être un objet JSON ; ses propriétés deviennent des variables de template. --set surcharge les clés de premier niveau littérales avec des chaînes. Utilisez JSON pour les objets imbriqués, tableaux, nombres et booléens.

Choisissez une seule source de template (fichier, -t ou stdin) et une seule source de données (--data ou --data-json). Une seule entrée peut lire stdin. Sans fichier template ou -t, Knap lit le template depuis stdin.

La sortie par défaut est stdout. -o crée les répertoires parents et écrase la destination après le rendu réussi. Les erreurs sortent avec le statut 1 ; les diagnostics vont sur stderr. Les avertissements peuvent accompagner une sortie réussie.

Templates

Utilisez {{ variable }} pour les valeurs, | pour les filtres, et {% ... %} pour la logique. Par exemple, enregistrez ceci comme template.md :

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

{{ content }}

Utilisez yaml_property pour les propriétés de frontmatter complètes afin que les valeurs soient correctement citées et indentées. Le CLI inclut des filtres standard, mais ne fournit pas les variables du navigateur Web Clipper, les sélecteurs, les invites ou les filtres HTML dépendants du DOM. Fournissez les variables via JSON.

Vérifiez un template avant le rendu :

knap validate template.md

La validation vérifie la syntaxe, les noms de filtres et les arguments de filtres statiques sans données ni sortie de fichier. Elle ne vérifie pas l'existence des variables, les valeurs au moment de l'exécution ou les arguments dynamiques ; effectuez le rendu avec des données réelles pour vérifier le comportement au moment de l'exécution. Les diagnostics vont sur stderr et incluent les commandes d'aide pertinentes.

Pipeline Defuddle

Extrayez une page web en JSON avec du contenu Markdown, puis rendez-la dans une note :

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

Les propriétés JSON de Defuddle, telles que title et content, deviennent directement des variables de template.

Rendu par lot

Créez un fichier par ligne CSV, objet de tableau JSON ou fichier JSON dans un dossier :

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

Utilisez --data articles.json pour un tableau ou --data ./articles pour un dossier d'objets JSON. Les en-têtes CSV deviennent des noms de variables et les valeurs restent des chaînes. Les données envoyées par pipe sont JSON par défaut ; ajoutez --format csv pour du CSV envoyé par pipe.

Utilisez --dry-run pour valider et lister les chemins de sortie sans écrire de fichiers. Les fichiers existants nécessitent --overwrite, y compris lors d'une exécution sèche. Les noms de sortie en doublon au sein d'un lot sont des erreurs même avec --overwrite.

Les templates de nom de fichier doivent produire un seul nom de fichier avec son extension, sans répertoires. Utilisez safe_name pour les noms dérivés des données. Sans --filename, Knap préserve les noms de base JSON sources ou numérote les lignes CSV et les éléments de tableau comme 1.md, 2.md, et ainsi de suite.