¿Qué hace knap?
Usa Knap CLI para renderizar plantillas Markdown con variables, filtros y lógica.
Si no está instalado: npm install -g knap (requiere Node.js 20 o posterior). Alternativamente, usa npx knap.
Ejecuta knap --help para ver los comandos y opciones disponibles. Descubre el lenguaje a través de la referencia offline del CLI:
knap help syntax
knap help filters
knap help filter date
knap help tags
knap help tag for
Usa las listas para encontrar nombres, luego solicita ayuda individual para sintaxis, parámetros y ejemplos con salida esperada.
Uso
Renderiza una plantilla con variables JSON:
knap render template.md --data article.json -o note.md
Proporciona una plantilla y datos en línea:
knap render -t '# {{ title | trim }}' --data-json '{"title":"Hola"}'
Sobrescribe una variable o canaliza datos JSON:
knap render template.md --data article.json --set 'title=Título personalizado'
cat article.json | knap render template.md --data -
Los datos deben ser un objeto JSON; sus propiedades se convierten en variables de la plantilla. --set sobrescribe claves literales de nivel superior con cadenas. Usa JSON para objetos anidados, arreglos, números y booleanos.
Elige una fuente de plantilla (archivo, -t o stdin) y una fuente de datos (--data o --data-json). Solo una entrada puede leer de stdin. Sin un archivo de plantilla o -t, Knap lee la plantilla desde stdin.
La salida por defecto es stdout. -o crea directorios padres y sobrescribe el destino después de que el renderizado se complete con éxito. Los errores salen con estado 1; los diagnósticos van a stderr. Las advertencias pueden acompañar a la salida exitosa.
Plantillas
Usa {{ variable }} para valores, | para filtros y {% ... %} para lógica. Por ejemplo, guarda esto como template.md:
---
{{ title | yaml_property:"title" }}
{{ tags | yaml_property:"tags" }}
---
# {{ title | trim }}
{% if author %}
Por {{ author }}
{% endif %}
{{ content }}
Usa yaml_property para propiedades completas de frontmatter, de modo que los valores se citen y sangren correctamente. El CLI incluye filtros estándar, pero no proporciona variables de navegador de Web Clipper, selectores, indicaciones ni filtros HTML dependientes del DOM. Proporciona variables a través de JSON.
Revisa una plantilla antes de renderizar:
knap validate template.md
La validación verifica la sintaxis, los nombres de filtros y los argumentos estáticos de los filtros sin datos ni salida a archivo. No verifica la existencia de variables, valores en tiempo de ejecución ni argumentos dinámicos; renderiza con datos reales para verificar el comportamiento en tiempo de ejecución. Los diagnósticos van a stderr e incluyen comandos de ayuda relevantes.
Pipeline Defuddle
Extrae una página web como JSON con contenido Markdown, luego renderízalo en una nota:
defuddle parse https://example.com/article --md --json \
| knap render template.md --data - -o note.md
Las propiedades JSON de Defuddle, como title y content, se convierten directamente en variables de la plantilla.
Renderizado por lotes
Crea un archivo por cada fila de CSV, objeto de arreglo JSON o archivo JSON en una carpeta:
knap batch template.md --data articles.csv --output-dir notes \
--filename '{{ title | safe_name }}.md'
Usa --data articles.json para un arreglo o --data ./articles para una carpeta de objetos JSON. Los encabezados CSV se convierten en nombres de variable y los valores permanecen como cadenas. Los datos canalizados por defecto son JSON; agrega --format csv para CSV canalizado.
Usa --dry-run para validar y listar las rutas de salida sin escribir archivos. Los archivos existentes requieren --overwrite, incluso durante una simulación. Los nombres de salida duplicados dentro de un lote son errores incluso con --overwrite.
Las plantillas de nombre de archivo deben producir un solo nombre de archivo con su extensión, sin directorios. Usa safe_name para nombres derivados de datos. Sin --filename, Knap conserva los nombres base JSON de origen o numera las filas de CSV y los elementos del arreglo como 1.md, 2.md, etc.