La documentación de software hoy es mucho más que una tarea obligatoria. Es parte del proceso de desarrollo y debe ser tan ágil, versionable y automatizable como el código fuente en sí. Los documentos de oficina clásicos o los wikis propietarios pronto se enfrentan a sus límites. Los cambios son difíciles de rastrear, la colaboración es engorrosa y la integración en pipelines de CI/CD es casi imposible.

AsciiDoc y Kroki abordan precisamente estos puntos. Ambas herramientas representan el enfoque Docs-as-Code, en el que la documentación se trata como código fuente. AsciiDoc ofrece un lenguaje textual expresivo para documentación técnica que se puede gestionar en Git y procesar de forma automatizada. Kroki complementa esto con la posibilidad de incrustar diagramas directamente en el documento y renderizarlos automáticamente. De este modo, las desarrolladoras y los desarrolladores pueden utilizar diagramas sin tener que instalar herramientas adicionales.

La combinación no es nueva, pero aporta un claro valor añadido: los contenidos y las visualizaciones permanecen en el mismo repositorio, los cambios se pueden rastrear en cualquier momento y los formatos de salida, desde HTML hasta PDF, pueden generarse de forma automatizada. Así, la documentación se convierte en un componente sólido y reproducible del desarrollo de software. Permanece transparente, flexible e independiente de plataformas propietarias.

¿Qué es AsciiDoc

AsciiDoc es un lenguaje de marcado desarrollado específicamente para documentación técnica. A diferencia de los documentos de oficina clásicos o de los editores WYSIWYG, AsciiDoc separa de manera consistente el contenido y la presentación. El texto se escribe en una sintaxis fácil de leer y luego se puede convertir a diferentes formatos de salida como HTML, PDF o DocBook.

¿Por qué AsciiDoc?

AsciiDoc sigue la misma idea que Markdown, pero ofrece muchas más funciones. Admite tablas, referencias cruzadas, variables, includes, notas al pie, tablas de contenido y extensiones como la inclusión de diagramas. Esto lo hace adecuado no solo para simples archivos README, sino también para manuales extensos, especificaciones o materiales de formación.

Ventajas en el desarrollo de software

  • Control de versiones: Dado que AsciiDoc es texto puro, se puede utilizar sin problemas en Git u otros sistemas de gestión de versiones. Los cambios son transparentes y las diferencias entre versiones claramente visibles.

  • Automatización: Los documentos AsciiDoc pueden formar parte de una pipeline de compilación. La documentación se puede generar junto con el software desde el mismo repositorio. De este modo, la documentación se convierte en un componente integrado del proceso de desarrollo y no en un paso posterior.

  • Reutilización: Los contenidos se pueden estructurar de forma modular y reutilizar mediante instrucciones include. Esto ahorra tiempo y evita redundancias, por ejemplo en secciones recurrentes como textos de licencia o notas estándar.

  • Integración de diagramas: En combinación con Asciidoctor-Diagram y Kroki, se pueden incrustar diagramas directamente en el texto. El código fuente y la visualización permanecen juntos en el repositorio, lo que simplifica enormemente el mantenimiento.

  • Independencia de formatos propietarios: AsciiDoc es abierto y estandarizado. No existe dependencia de fabricantes o programas específicos. Esto hace que la documentación sea a prueba de futuro y portátil.

AsciiDoc es una base robusta para la documentación técnica en proyectos de software. Combina la simplicidad de los archivos de texto con la expresividad de un lenguaje de marcado completo. Especialmente en el ámbito del desarrollo de software, la integración continua y los procesos DevOps, aporta claras ventajas: la documentación se vuelve versionable, automatizable y estrechamente vinculada al código fuente.

¿Qué es Kroki

Kroki es un servicio de código abierto que genera automáticamente diagramas a partir de descripciones textuales. En lugar de instalar localmente programas individuales como PlantUML, Graphviz o Mermaid, Kroki ofrece una interfaz HTTP unificada. Se envía un archivo de texto al servicio y se recibe una gráfica en el formato deseado, por ejemplo SVG o PNG.

Qué lenguajes de diagramas se admiten

Kroki integra una gran selección de motores. Esto incluye diagramas UML mediante PlantUML, diagramas de arquitectura con C4, representaciones de procesos en BPMN, redes con Graphviz y muchos más. Esto hace posible combinar diferentes notaciones en una documentación sin que el lector o el autor tengan que instalar software adicional.

Ventajas en el día a día del desarrollo

La mayor ventaja radica en la unificación. En lugar de mantener diferentes herramientas e instalaciones, basta con un único servidor Kroki. Esto ahorra tiempo en la configuración y reduce dependencias.

Otro aspecto es la automatización. Dado que Kroki se accede mediante una API, se puede integrar fácilmente en pipelines de CI/CD. Así, la documentación se genera automáticamente, incluidos los diagramas correspondientes. Los cambios en el código fuente o en las descripciones de los diagramas se reflejan directamente en los documentos generados sin que nadie tenga que exportar manualmente una gráfica de nuevo.

También en equipos Kroki aporta ventajas. Todos los participantes acceden al mismo servicio y trabajan con las mismas versiones de los motores. Esto evita discrepancias entre instalaciones locales y garantiza resultados reproducibles.

Conexión con AsciiDoc

Kroki resulta especialmente interesante en combinación con AsciiDoc. AsciiDoc permite incrustar código de diagramas directamente en la documentación. Normalmente se requeriría un backend local como PlantUML o Mermaid para ello. Sin embargo, con Kroki basta con un simple parámetro de configuración.

Instalación

AsciiDoc

Para trabajar con AsciiDoc necesitas un motor de renderizado. El más extendido es Asciidoctor. Este convierte archivos AsciiDoc a HTML o PDF. Para el procesamiento de diagramas se utiliza además el plugin Asciidoctor Diagram.

Asciidoctor está escrito en Ruby. Por ello Ruby debe estar instalado en el sistema. En Windows 11 se recomienda la instalación a través de RubyInstaller.

Una vez que Ruby está configurado, instalas los paquetes necesarios con el gestor de paquetes Ruby gem.
Para renderizar diagramas con Kroki directamente en AsciiDoc, se recomienda usar la extensión asciidoctor-kroki. Mientras que asciidoctor-diagram intenta invocar herramientas locales como PlantUML o Graphviz, asciidoctor-kroki conecta con el servidor Kroki directamente a través de HTTP.

Para probar, creamos un archivo de prueba helloworld.adoc con el siguiente contenido:

Con el siguiente comando conviertes el archivo a HTML:

Visual Studio Code ofrece con la extensión AsciiDoc by Asciidoctor la posibilidad de mostrar archivos AsciiDoc directamente en el editor como vista previa. Mientras en la ventana izquierda se escribe el texto fuente AsciiDoc, la extensión muestra en la ventana derecha el HTML renderizado. De esta forma, los cambios en el documento se pueden verificar de inmediato sin tener que convertir manualmente el texto a HTML.

Kroki

En Windows, Kroki se puede ejecutar muy fácilmente con Docker Desktop. Docker se encarga de la instalación y gestión completa de la aplicación. No se necesita configuración adicional.

De este modo, Kroki se descarga automáticamente desde Docker Hub y se inicia en segundo plano. A través del navegador, el servicio queda disponible en http://localhost:8000. Así, tienes de inmediato un servidor Kroki operativo que se puede usar para generar diagramas.

El texto mostrado es un documento AsciiDoc completo que renderiza un diagrama con Kroki. En la primera línea está el título del documento. Con la línea :kroki-server-url: http://localhost:8000 se establece que Kroki se use como servidor para la generación de diagramas. El bloque [plantuml, format=svg] indica un diagrama PlantUML que debe emitirse como SVG. Entre las líneas —- se encuentra el código PlantUML en sí. Este describe un diagrama de secuencia sencillo en el que Alice envía un mensaje a Bob y Bob reacciona enviando una respuesta. Al renderizarse, este código se envía automáticamente a Kroki y se inserta como gráfica en el documento final.

Este comando convierte un archivo AsciiDoc a HTML y renderiza los diagramas incluidos mediante el servidor Kroki.

Documentos de ejemplo

Aquí se muestra un ejemplo que demuestra las funciones más importantes de AsciiDoc. No es exhaustivo, sino que pretende dar una idea de cómo se pueden usar diferentes formatos.