Markdown te está frenando
(newsletter.bphogan.com)- Markdown, ampliamente usado para escribir documentación de desarrollo, es popular por su simplicidad y accesibilidad, pero tiene límites en la documentación técnica a gran escala debido a su falta de expresividad estructural
- Markdown funciona como un sistema de tipos implícito, por lo que no es posible validar consistencia ni esquemas, y además existen problemas de compatibilidad entre distintas variantes (flavors) de Markdown
- Sintaxis extendidas como MDX aumentan la expresividad, pero terminan incrementando la complejidad por la falta de portabilidad y estandarización entre sistemas
- reStructuredText, AsciiDoc, DocBook y DITA ofrecen estructura explícita y marcado semántico (semantic markup), lo que fortalece la reutilización y la interpretabilidad por máquinas
- Para documentos pequeños, Markdown es suficiente, pero para la gestión documental a gran escala y multicanal hace falta migrar a formatos estructurados
Los límites estructurales de Markdown
- Markdown permite crear documentos agradables de leer en GitHub o en sitios estáticos con una sintaxis simple y fácil de leer para humanos
- Sin embargo, no puede describir el significado del contenido, por lo que carece de información estructural que las máquinas puedan comprender
- Motores de búsqueda, LLM, IDE y agentes de IA aprovechan la estructura semántica de los documentos, pero Markdown solo genera etiquetas HTML limitadas
- Debido a las diferencias de sintaxis según la plataforma, Markdown provoca problemas de inconsistencia al reutilizar o integrar contenido
- Como resultado, Markdown termina siendo un formato de mínimo común denominador, poco adecuado para gestionar documentación compleja
El problema de los tipos implícitos en Markdown
- Markdown es un formato sin esquema ni definición de tipos explícitos, por lo que un mismo título o lista puede tener significados distintos según el contexto
- Existen muchas variantes (flavors) de Markdown, lo que produce diferencias de renderizado entre herramientas
- Ejemplo: algunas herramientas soportan notas al pie, mientras que otras las ignoran
- MDX amplía la expresividad al insertar componentes de React, pero sufre baja portabilidad por problemas de compatibilidad entre sistemas
- Estas extensiones intentan compensar las limitaciones de Markdown, pero no dejan de ser soluciones temporales no estandarizadas
La importancia del marcado semántico
- El marcado semántico describe el significado del contenido, no su forma
- Ejemplo: un “paso (step)” y un “elemento de lista” pueden verse igual, pero no significan lo mismo
- HTML5 introdujo etiquetas basadas en significado como
<section>,<article>y<aside>para reforzar la expresión estructural - Ventajas clave del marcado semántico
- Transformación y reutilización: el mismo contenido puede convertirse a HTML, PDF, ePub y otros formatos
- Interpretabilidad por máquinas: los LLM o agentes pueden reconocer la estructura con claridad y responder con mayor precisión
- Como Markdown no aporta esta información estructural, se produce pérdida de información en el posprocesamiento o la conversión
Comparación de formatos alternativos
- reStructuredText
- Formato usado por Sphinx en el ecosistema de Python, que expresa significado estructural mediante directivas (directive) y roles (role)
- Soporta elementos estructurales explícitos como bloques de código, notas (
note) y referencias cruzadas (:ref:) - Es adecuado para documentación técnica a gran escala y soporta generación de HTML y PDF
- AsciiDoc
- Un formato de texto semántico que ofrece atributos (attribute), contenido condicional y funciones de include
- Soporta expresiones especializadas para documentación técnica, como avisos
NOTEyWARNING, elementos de UI y notación de atajos de teclado - Puede convertirse a HTML, PDF, ePub, DocBook y más mediante AsciiDoctor
- DocBook (XML)
- Un modelo basado en XML para publicación técnica que ofrece un sistema de etiquetas con significado como
<command>,<note>y<xref> - Incluye etiquetas necesarias para documentación especializada, como glosarios, índices, elementos de UI y nombres de funciones
- Puede transformarse a diversos formatos de salida mediante hojas de estilo XSLT
- Es ventajoso para la validación estructural de documentos a gran escala y la generación de índices
- Un modelo basado en XML para publicación técnica que ofrece un sistema de etiquetas con significado como
- DITA (Darwin Information Typing Architecture)
- Una estructura modular basada en XML usada como estándar de documentación técnica empresarial
- Como arquitectura XML basada en temas, define con claridad estructuras procedimentales como
<task>y<step> - Se usa como estándar de gestión documental empresarial para reutilización de contenido (
conref), filtrado y publicación multicanal - Soporta la automatización del renderizado y la conversión mediante DITA Open Toolkit
Por qué XML sigue siendo necesario aunque parezca incómodo
- Markdown es liviano, pero también una solución provisional carente de estructura, estándar y consistencia
- Si estás agregando complejidad a Markdown con MDX, plugins o scripts personalizados,
adoptar directamente un formato estructurado será más estable a largo plazo
Entonces, ¿qué conviene hacer?
- Para documentos pequeños como README o documentación de una sola vez, Markdown es suficiente, pero para documentación a gran escala, reutilizable y multicanal, reStructuredText, AsciiDoc, DocBook y DITA son más adecuados
- Si necesitas documentos de planificación, documentación para desarrolladores, reutilización o gestión a gran escala, conviene evaluar primero reST/AsciiDoc y luego DocBook/DITA
- Lo ideal es usar como fuente el formato con la estructura más rica posible y, si hace falta, convertir después a Markdown
- Markdown es útil como formato de salida, pero usarlo como fuente de verdad (source of truth) dificulta la expansión estructural
- Lo óptimo es mantener la fuente en un formato rico en estructura semántica y usar Markdown como salida downstream
7 comentarios
¿rst es un formato basado en XML? Es la primera vez que escucho eso. El resumen está raro.
Parece que el título quedó así porque, en el resumen, se hablaba del criterio de selección agrupándolo con otros formatos XML.
Lo corregí para que coincida con el original.
Si hace falta, usas HTML en Markdown y le pegas Mermaid, y más o menos funciona... pero más allá de eso, parece que el trabajo se vuelve hacer documentos para los documentos.
Las personas van primero que la IA. No robes lo que escribí. Y vienen a hablar de semántica.
Si se va a usar una sintaxis especial, entonces también hay que dar soporte fluido a toda otra curva de aprendizaje, herramientas de parsing dedicadas, visores, editores, etc. A ese nivel, quizá sería mejor simplemente usar Google Docs o Notion, que se pueden conectar sin problemas con la mayoría de los servicios de IA.
Opiniones en Hacker News
La esencia de Markdown es su amplísimo soporte, algo que otros lenguajes no tienen La mayoría de las alternativas requieren herramientas aparte y no se pueden usar en entornos donde Markdown ya está soportado Incluso Google Docs admite pegar Markdown como una función oculta Aunque no sea perfecto, su ventaja es que “se puede usar en cualquier lado” Así como HTML era más simple que SGML pero terminó volviéndose estándar porque los navegadores lo soportaban, Markdown también puede evolucionar con el tiempo La ambigüedad de la estandarización, la falta de funciones y los problemas de compatibilidad son parecidos a la época de HTML4 En vez de reemplazarlo por completo, creo que una evolución gradual es el camino más realista
Markdown puede incluir etiquetas HTML en cualquier parte Eso está indicado incluso en la documentación oficial Así que la limitación que menciona el autor en realidad no existe
o, entonces no hay razón para usar Markdown Si al final la respuesta es “usa HTML”, desaparece la razón de ser de MarkdownEn la universidad, cuando estudiaba física, escribía trabajos en LaTeX En química usaban Word, así que el estándar cambia según el área La versión de TeX expresa su grado de completitud acercándose al valor de π La versión actual es 3.141592653 y se ha mantenido estable durante 47 años Ver wiki de TeX y explicación de la versión π Para herramientas CLI, el formato manpage también es útil
Markdown es como un producto mínimo viable (MVP) Es fácil de aprender y, aunque no se renderice, sigue siendo fácil de leer Para hacer PDF me pasé de AsciiDoc a Typst, porque resolvía problemas de accesibilidad Pero ningún lenguaje de marcado mejora por sí solo la calidad de un texto Cambiar de pluma no hace que uno escriba mejor
El tono de este artículo es que “Markdown frena el avance de los LLM” Pero la idea de que se puede obtener automáticamente riqueza semántica parte de una premisa poco realista Dentro de un equipo no hay tiempo para hacer ese trabajo, y Markdown es suficiente Igual que en las discusiones sobre la web semántica, al final todo depende de quién gestiona los datos
Yo escribo mi blog con Org-mode + Emacs Me gusta especialmente poder enlazar bloques de código y ejecutarlos dentro del documento También probé plataformas como Blorgit y lazyblorg, pero como configurarlas daba flojera, exporto directamente a HTML y lo subo al servidor con rsync Lo despliego agregando un índice con un script Ruby Es mucho más expresivo y natural que Markdown
Coincido en parte con la idea de que “Markdown tiene poca estructura”, pero me incomoda su enfoque binario Antes de elegir un formato, primero habría que entender qué estructura se necesita Por eso me resulta un poco molesto y difícil de aceptar al mismo tiempo
Presentar DITA como alternativa a Markdown es un argumento totalmente fuera de lugar DITA es un sistema XML empresarial a gran escala, con un propósito completamente distinto al de Markdown Solo tiene sentido en entornos con más de 5 mil personas y líneas de productos multilingües Si estás en una situación donde usarías Markdown, DITA definitivamente no encaja Ambos serían una pérdida de tiempo
Llevo más de 10 años usando Markdown y sigue funcionando bien Lo que dice el artículo no está completamente mal, pero no es un problema que los usuarios de Markdown sientan Si hace falta, simplemente se usa otra cosa Aun así, el título estaba bueno y por eso lo leí unos 5 minutos
Es raro que mencionen MyST como una forma de Markdown y luego vuelvan a poner como ejemplo a reStructuredText (rST) El propósito de MyST es precisamente ser un reemplazo de rST Su sintaxis se siente como Markdown, pero también soporta significado estructural,
directive,roley demás En el issue de Sphinx también hay discusión relacionadaÚltimamente se ven muchos textos de este tipo.
Archivos de texto, Markdown, formatos más estructurados.
A medida que eso va cambiando, no es que haya una única respuesta correcta; simplemente hay que usar el formato adecuado en el momento adecuado.
Y además, si uno siempre intenta hacer todo con un solo archivo, terminan apareciendo problemas, así que clasificar y organizar según el tema es algo inevitable.