Que fait knap ?
Utilisez Knap CLI pour générer des modèles Markdown avec variables, filtres et logique.
Si non installé : npm install -g knap (nécessite Node.js 20 ou ultérieur). Vous pouvez également utiliser npx knap.
Exécutez knap --help pour voir les commandes et options disponibles. Découvrez le langage via la référence intégrée 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 de l'aide individuelle pour la syntaxe, les paramètres et les exemples avec le résultat attendu.
Utilisation
Générer un modèle avec des variables JSON :
knap render template.md --data article.json -o note.md
Fournir un modèle et des données en ligne :
knap render -t '# {{ title | trim }}' --data-json '{"title":"Bonjour"}'
Surcharger une variable ou rediriger des données JSON :
knap render template.md --data article.json --set 'title=Titre personnalisé'
cat article.json | knap render template.md --data -
Les données doivent être un objet JSON ; ses propriétés deviennent des variables de modèle. --set remplace les clés de premier niveau littérales par des chaînes. Utilisez JSON pour les objets imbriqués, tableaux, nombres et booléens.
Choisissez une source de modèle (fichier, -t ou entrée standard) et une source de données (--data ou --data-json). Une seule entrée peut lire l'entrée standard. Sans fichier de modèle ni -t, Knap lit le modèle depuis l'entrée standard.
La sortie est par défaut sur la sortie standard. -o crée les répertoires parents et écrase la destination après une génération réussie. Les erreurs renvoient un code de sortie 1 ; les diagnostics vont sur la sortie d'erreur. Des avertissements peuvent accompagner une sortie réussie.
Modèles
Utilisez {{ variable }} pour les valeurs, | pour les filtres, et {% ... %} pour la logique. Par exemple, enregistrez ceci dans template.md :
---
{{ title | yaml_property:"title" }}
{{ tags | yaml_property:"tags" }}
---
# {{ title | trim }}
{% if author %}
Par {{ author }}
{% endif %}
{{ content }}
Utilisez yaml_property pour les propriétés complètes de l'en-tête YAML afin que les valeurs soient correctement citées et indentées. Le CLI inclut des filtres standard, mais ne fournit pas de variables de navigateur Web Clipper, de sélecteurs, d'invites ou de filtres HTML dépendants du DOM. Fournissez les variables via JSON.
Vérifiez un modèle avant de le générer :
knap validate template.md
La validation vérifie la syntaxe, les noms de filtres et les arguments statiques des filtres sans données ni fichier de sortie. Elle ne vérifie pas l'existence des variables, les valeurs d'exécution ou les arguments dynamiques ; générez avec des données réelles pour vérifier le comportement à l'exécution. Les diagnostics vont sur la sortie d'erreur et incluent des commandes d'aide pertinentes.
Pipeline Defuddle
Extrayez une page web au format JSON avec du contenu Markdown, puis générez-la en 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 modèle.
Génération par lots
Créez un fichier par ligne CSV, par objet d'un tableau JSON, ou par 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 redirigées par défaut sont en JSON ; ajoutez --format csv pour des données CSV redirigées.
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'un essai à blanc. Les noms de sortie en double dans un même lot sont des erreurs, même avec --overwrite.
Les modèles de noms de fichiers doivent produire un nom de fichier unique avec son extension, sans répertoires. Utilisez safe_name pour les noms dérivés des données. Sans --filename, Knap conserve les noms de base JSON sources ou numérote les lignes CSV et les éléments de tableau sous forme de 1.md, 2.md, etc.