Pandoc con Lua: automatiza documentos sin fricción

Si trabajas con documentación, contenidos largos o entregas que se repiten cada semana, seguro ya viste el mismo problema varias veces: el texto cambia poco, pero el formato, los metadatos y las salidas tienen que quedar consistentes. Copiar y pegar ajustes a mano funciona una vez. A la tercera ya empiezan los errores: títulos mal convertidos, imágenes fuera de lugar, secciones que no deberían salir en PDF y enlaces que se rompen al pasar de Markdown a HTML o DOCX.

Ahí es donde Pandoc con Lua te ahorra tiempo de verdad. No se trata solo de convertir archivos entre formatos. Se trata de meter reglas de transformación dentro del flujo: limpiar el documento, reescribir bloques, cambiar atributos, normalizar estilos y dejar que el proceso haga el trabajo repetitivo por ti. Si haces documentación técnica, publicaciones internas, ebooks o material académico, esto te sirve para producir más con menos fricción.

Qué hace Pandoc con Lua y por qué te conviene

Pandoc ya es útil por sí solo porque convierte entre muchos formatos. Puedes pasar de Markdown a HTML, PDF, DOCX, EPUB, LaTeX y más. Pero cuando necesitas reglas finas, el salto real está en Lua filters. Según la documentación oficial de Pandoc, estos filtros te permiten recorrer el documento como un árbol de elementos y modificarlo antes de la salida final. Eso te da control sin tener que tocar el contenido original a mano.

La idea práctica es simple: escribes una función en Lua que Pandoc ejecuta sobre elementos del documento, como párrafos, enlaces, imágenes, encabezados o tablas. Si encuentra algo que coincide con tu regla, lo transforma. Si no, lo deja pasar. Eso te permite automatizar tareas como cambiar estilos de títulos, añadir clases CSS, reescribir rutas de imágenes o eliminar secciones enteras según el formato de salida.

La documentación oficial de Lua filters está aquí: https://pandoc.org/lua-filters.html. Si quieres ver cómo encaja el modelo de documentos de Pandoc, también te conviene leer la referencia de la API Lua: https://pandoc.org/lua-filters.html#pandoc-api.

El caso de uso real: un mismo contenido, varias salidas

Imagina que tu equipo escribe una guía técnica en Markdown y necesita publicarla en tres formatos: web, PDF y un DOCX para revisión legal. En web quieres enlaces limpios, en PDF necesitas una portada y numeración, y en DOCX quieres ciertos bloques ocultos. Hacer eso manualmente en cada exportación es una receta para inconsistencias.

Con un filtro Lua puedes aplicar reglas distintas según el formato de salida. Por ejemplo, puedes mantener un solo archivo fuente y hacer que Pandoc agregue una nota al pie solo en PDF, o que convierta una imagen en figura con leyenda solo para HTML. No estás duplicando contenido, estás moviendo lógica al proceso.

Esto también sirve para equipos pequeños. Si eres editor, technical writer o devrel, probablemente no quieres administrar un sistema enorme. Quieres algo que puedas versionar, revisar en Git y ejecutar con un comando. Lua encaja bien ahí porque es ligero, legible y fácil de integrar en scripts.

Cómo funciona un filtro Lua en Pandoc

Un filtro Lua es un archivo .lua que define funciones para elementos del documento. Pandoc procesa el contenido internamente y llama a esas funciones cuando encuentra un tipo de elemento. Por ejemplo, si defines Header, se ejecuta cada vez que aparece un encabezado. Si defines Image, se ejecuta cada vez que aparece una imagen.

La lógica básica es esta: recibes un elemento, inspeccionas sus propiedades y devuelves una versión modificada o nil si no quieres cambiar nada. Eso te deja trabajar con estructuras reales del documento, no con texto plano. Es una diferencia importante porque un documento no es solo texto; también tiene jerarquía, atributos y formato semántico.

Un ejemplo mínimo para revisar la estructura de un encabezado podría verse así:

function Header(el)
  if el.level == 2 then
    el.classes:insert("section-title")
    return el
  end
end

Ese filtro añade la clase section-title a todos los encabezados de nivel 2. No toca el texto, no rompe el contenido y puede usarse luego en CSS o en otro procesador. Es una forma limpia de introducir reglas de presentación sin ensuciar el Markdown original.

Anatomía de un filtro

Un filtro suele tener tres piezas: el tipo de elemento, la condición y la transformación. El tipo puede ser Para, Str, Link, Image, Header, Div, entre otros. La condición define cuándo actúa. La transformación devuelve un nuevo elemento, un bloque vacío o el mismo elemento con cambios.

Por ejemplo, si quieres reemplazar una palabra específica solo cuando aparece como texto suelto, puedes usar Str. Si quieres envolver un bloque completo en una clase, puedes usar Div. Y si quieres actuar sobre tablas o listas, también puedes hacerlo, siempre que conozcas la estructura que Pandoc expone.

Qué puedes modificar sin pelearte con el contenido

Con Lua filters puedes hacer tareas muy concretas que suelen aparecer en flujos editoriales reales:

• Cambiar el texto de enlaces externos según el dominio.
• Añadir clases CSS a imágenes que vienen de una carpeta específica.
• Eliminar bloques marcados como borrador.
• Convertir abreviaturas internas a su forma expandida.
• Insertar avisos o notas solo en una salida concreta.
• Normalizar encabezados para que el PDF y el HTML tengan la misma jerarquía.

No necesitas usar todo desde el día uno. De hecho, lo mejor es empezar con una sola regla que hoy haces a mano y convertirla en filtro. Ese primer caso te enseña la estructura y te deja una base para crecer.

Ejemplos prácticos que sí sirven en producción

La parte buena de Lua filters es que no se quedan en teoría. Puedes usarlos para resolver problemas que aparecen cada semana en documentación, catálogos, manuales y contenidos largos. Lo importante es elegir tareas repetitivas y bien definidas. Si la regla es clara, el filtro suele ser corto.

Un escenario común es el de las imágenes. Tal vez tu equipo guarda archivos con nombres inconsistentes, pero quieres que en la salida HTML todas las imágenes de una carpeta tengan una clase específica. Otro caso es el de los encabezados: quizá necesitas que los títulos de nivel 1 se conviertan en h2 en una salida especial, o que ciertos bloques se omitan en DOCX.

Aquí tienes un ejemplo que agrega una clase a las imágenes que vienen de una ruta concreta:

function Image(img)
  if img.src:match("^assets/figures/") then
    img.classes:insert("figure--editorial")
    return img
  end
end

Ese filtro no inventa nada raro. Solo detecta una ruta y etiqueta la imagen. Luego puedes usar esa clase en CSS o en otro paso del pipeline. Si tu publicación tiene decenas de imágenes, esto evita editar una por una.

Reescribir enlaces y notas internas

Otro uso útil es reescribir enlaces. Si migras documentación desde un sitio viejo, puedes cambiar dominios o rutas sin tocar cada archivo manualmente. También puedes detectar enlaces internos con un patrón y normalizarlos para que apunten al formato correcto.

Supón que quieres reemplazar un dominio antiguo por uno nuevo:

function Link(link)
  if link.target:match("oldsite%.example%.com") then
    link.target = link.target:gsub("oldsite%.example%.com", "docs.example.com")
    return link
  end
end

Eso te ahorra búsquedas globales en cientos de archivos. Y si mañana cambia otra vez el dominio, ajustas una sola línea. En flujos editoriales, ese tipo de mantenimiento vale más que una optimización teórica.

Tabla de transformaciones típicas

Esta tabla resume algo clave: no necesitas automatizar todo. Basta con atacar los puntos donde el error humano cuesta más tiempo.

Un flujo de trabajo que puedes copiar

Si quieres empezar sin complicarte, te conviene pensar en Pandoc con Lua como una capa más del pipeline, no como una herramienta aislada. Tu contenido entra en Markdown o en el formato fuente que uses. Pandoc lo parsea. El filtro Lua aplica reglas. Luego sale a HTML, PDF, DOCX o el formato que necesites.

Ese flujo es especialmente útil si trabajas con repositorios en Git. Puedes versionar el contenido, el filtro y la configuración. Así, cuando alguien pregunta por qué un bloque salió distinto, puedes revisar el commit exacto. Eso es mucho mejor que depender de ajustes manuales en una interfaz gráfica que nadie documentó.

Una forma razonable de organizarlo sería esta:

1. Define una regla pequeña y repetible, como cambiar clases en imágenes.
2. Escribe el filtro en un archivo .lua separado.
3. Prueba la salida con un documento corto antes de usarlo en producción.
4. Guarda el filtro en Git junto al contenido.
5. Documenta qué hace y en qué formatos aplica.
6. Añade una prueba de ejemplo si tu equipo ya tiene automatización.

Si usas esto en documentación técnica, te conviene además separar reglas por responsabilidad. Un archivo para imágenes, otro para encabezados y otro para contenido condicional. No mezcles veinte transformaciones en un solo script si puedes evitarlo. Mantenerlo pequeño hace que cualquiera del equipo lo entienda.

Ejecución desde la línea de comandos

Pandoc permite cargar filtros Lua directamente desde la línea de comandos. Eso simplifica mucho el uso en CI o en scripts locales. Un ejemplo típico sería algo así:

pandoc input.md -o output.html --lua-filter=filters/images.lua

Si necesitas varios filtros, puedes encadenarlos. Eso te deja separar lógica por tema y reutilizar piezas según el proyecto. También puedes combinar filtros con variables de entorno o con parámetros que tu propio script lea, según la complejidad que necesites.

En equipos pequeños, este enfoque suele ser suficiente. No hace falta montar una arquitectura compleja para automatizar cinco reglas bien pensadas. Si el pipeline queda claro, ya ganaste bastante.

Buenas prácticas para no romper el documento

La parte delicada de automatizar documentos es que un cambio pequeño puede afectar mucho la salida. Por eso conviene trabajar con reglas explícitas y pruebas con documentos reales. No te fíes solo de un archivo de ejemplo demasiado limpio. Usa contenido con tablas, imágenes, enlaces, listas y encabezados irregulares.

También te conviene leer la documentación oficial sobre el modelo de datos de Pandoc antes de escribir filtros más complejos. Ahí entiendes qué devuelve cada tipo de elemento y cómo se representa el contenido. La referencia oficial está en https://pandoc.org/lua-filters.html y en la sección de la API Lua. Si entiendes la estructura, depuras mucho más rápido.

Hay otro punto práctico: no conviertas un filtro en un segundo sistema de plantillas. Si una regla pertenece al contenido, quizá debería vivir en el documento. Si pertenece a la salida, entonces sí tiene sentido en Lua. Esa separación te evita scripts difíciles de mantener.

Cómo probar sin perder tiempo

Una estrategia simple es usar un archivo de prueba con casos reales y compararlo con la salida esperada. No necesitas una suite enorme para empezar. Basta con cubrir los elementos que tu filtro toca de forma directa.

Puedes revisar, por ejemplo:

• Un encabezado con el nivel correcto.
• Una imagen con ruta esperada.
• Un enlace externo y uno interno.
• Un bloque que debería desaparecer en cierta salida.
• Una tabla con celdas de texto y celdas vacías.

Si tu filtro modifica solo una parte del documento, prueba solo esa parte. No intentes validar todo el universo en el primer intento. Lo importante es detectar regresiones cuando cambias una regla.

Cuándo no usar Lua filters

No siempre conviene meter lógica en un filtro. Si el cambio es puntual y manual, quizá sea más rápido editar el contenido. Si la regla depende de decisiones editoriales que cambian cada día, tal vez no vale la pena automatizarla todavía. Y si el equipo no puede mantener el script, el filtro se vuelve deuda técnica.

La señal correcta es esta: si la tarea se repite, tiene patrón y genera errores cuando se hace a mano, Lua filters probablemente sí te convienen. Si no, mejor deja el proceso simple.

Tabla resumen

Si tu flujo editorial depende de exportaciones repetidas, Pandoc con Lua te da una forma bastante limpia de mover lógica al pipeline. No reemplaza tu criterio editorial, pero sí quita trabajo mecánico y reduce errores tontos. Y eso, en producción, se nota rápido.