Markdown
Texto sin formato con unos pocos signos de formato
Qué es
Markdown permite escribir un documento como un archivo de texto corriente donde
unas pocas convenciones indican al conversor qué HTML producir: asteriscos
alrededor de una palabra para darle énfasis, una almohadilla ante un título, un
guion ante cada elemento de una lista y corchetes seguidos de paréntesis para un
enlace. El nombre abarca tanto la sintaxis como el programa con el que se
publicó inicialmente. Los archivos suelen terminar en .md o .markdown, y
también se llaman Markdown los dialectos que surgieron de él, como CommonMark y
GitHub Flavored Markdown (GFM).
John Gruber lo desarrolló en 2004 en colaboración con Aaron Swartz y escribió el primer conversor en Perl; su última versión, Markdown 1.0.1, está fechada el 17 de diciembre de 2004. Declaró que la prioridad era la legibilidad: un documento Markdown debía poder publicarse tal cual, como texto sin formato, sin parecer marcado con etiquetas o instrucciones de formato. Según escribió, la mayor influencia en la sintaxis fue la forma en que la gente ya daba formato a los correos de texto sin formato. Lo que la sintaxis no cubre se escribe como HTML entre el texto, sin cambios de modo ni delimitadores: en su planteamiento, Markdown es un formato de escritura y HTML, el de publicación.
Unas pocas líneas muestran casi todo:
El traslado llevó **una velada**, en tres pasos:
- detener las escrituras
- copiar los datos con `pg_dump`
- dirigir la [aplicación](https://example.com/app/) al nuevo servidorUn conversor lo transforma en un párrafo con un elemento strong, una lista de
tres elementos, un fragmento de código en línea y un enlace; el original sigue
pareciendo una nota que alguien escribió.
Por qué importa
El archivo fuente es el documento, y el texto sin formato sobrevive a todas las herramientas que lo rodean. Un archivo Markdown se abre en cualquier editor, se compara línea por línea en el control de versiones y se revisa con claridad en una solicitud de cambios. Ningún proveedor puede retirar el formato; trasladar un conjunto de escritos entre sistemas consiste en copiar archivos.
El precio es la ambigüedad. El proyecto CommonMark lo expresa sin rodeos: la descripción de Gruber no especifica la sintaxis de manera inequívoca, su script tenía errores y se actualizó por última vez en diciembre de 2004. En 2014 ya había decenas de implementaciones, cada una resolviendo las lagunas a su manera. Su ejemplo es un documento que se representa de una forma en una wiki de GitHub y de otra al convertirlo a DocBook con Pandoc. Como Markdown no rechaza ninguna entrada por error de sintaxis, la divergencia solo aparece cuando alguien mira el resultado. El proyecto remite a Babelmark 3, que ejecuta la misma entrada en más de veinte implementaciones para comprobar si coinciden.
CommonMark, iniciado en 2014, responde con una especificación escrita por John MacFarlane que vincula cada regla a ejemplos de entrada y al HTML exacto que deben producir: 652 en la versión 0.31.2, fechada el 28 de enero de 2024. GitHub define su dialecto, GFM, como un superconjunto estricto de CommonMark: añade tablas, elementos de listas de tareas, tachado, enlaces automáticos ampliados y un filtro que neutraliza una lista breve de etiquetas HTML sin procesar. Goldmark, el conversor Markdown de Hugo, se ajusta a la especificación CommonMark y es compatible con GFM.
Markdown también tiene nombre en el protocolo. Desde marzo de 2016, RFC 7763
registra text/markdown para toda la familia de sintaxis, con un parámetro
charset obligatorio y otro variant opcional que indica el dialecto del
archivo.
Cómo se aplica en la práctica
Las páginas escritas a mano de este sitio son Markdown, con la presentación definida mediante plantillas Go. La página de créditos enumera ambas herramientas junto a Hugo, el generador de sitios estáticos. La misma página incluye markdownlint entre los analizadores que mantienen correcto el código fuente, dentro de un control de calidad obligatorio donde todo diagnóstico es un error.
La página sobre cómo hacer un sitio legible para agentes de IA
utiliza el formato en el otro sentido: cada página de este sitio tiene una
versión Markdown en la misma dirección, accesible añadiendo index.md o
solicitando text/markdown. La compilación lee todas esas versiones en busca de
restos de marcado y rechaza la publicación si alguna es incorrecta. Basta una
solicitud para obtener la versión de esa página:
curl -sL https://engineer.company/ai-ready/index.mdUnas 50.000 palabras de documentación de software se escribieron en Markdown en GitHub, Craft y Confluence, muchas de ellas a mano. Cubrían la arquitectura, los procesos y los procedimientos que la gente preguntaba una y otra vez; se mantuvieron bajo control de versiones y fáciles de encontrar, y ayudaron a las nuevas incorporaciones a ponerse al día más deprisa.
Dónde surgen los problemas
La negrita se muestra como asteriscos. El lector ve dos asteriscos a cada lado de una palabra que debía estar en negrita, y todas las comprobaciones siguen aprobadas porque el HTML es válido y los enlaces funcionan. CommonMark solo abre el énfasis con una secuencia de asteriscos que cumpla las condiciones de apertura por la izquierda; si va seguida de puntuación, como el corchete de un enlace, solo cuenta si delante hay un espacio en blanco o un signo de puntuación. Una letra delante mantiene los asteriscos como texto literal; ocurre lo mismo con lo que añada un motor de plantillas antes de analizar Markdown: Hugo sustituye un shortcode por un marcador de letras y números. La plantilla de las versiones Markdown de este sitio documenta que quitar el espacio entre un shortcode y la negrita contigua rompió la negrita en 60 viñetas de tres idiomas. Conserve el espacio y compruebe la página representada, en lugar del original; el control de calidad obligatorio de este sitio lee el HTML compilado para detectar Markdown que llegue al lector como signos de puntuación.
El mismo archivo se representa de dos maneras. Una lista anidada se aplana en un sistema y se mantiene anidada en otro, o una almohadilla al principio de una línea crea un título en un conversor y queda como texto en el siguiente. Nada lo notifica porque Markdown no tiene errores de sintaxis que notificar. La causa es una diferencia de dialecto: dos conversores resuelven de forma distinta una de las lagunas originales. Indique el dialecto del proyecto, normalmente CommonMark o GFM, use un analizador que lo exija y pruebe las entradas dudosas en más de una implementación antes de depender de ellas.
La copia Markdown de una página contiene HTML. El lector de la versión de
texto encuentra elementos svg sin procesar o un teléfono que comienza con una
referencia numérica de carácter donde debería estar el signo más. Un componente
que produce HTML para la página web produce el mismo HTML en los demás formatos
si no se le indica lo contrario: Hugo busca la plantilla de un shortcode por
formato de salida y, si no existe, recurre a la de HTML. Las plantillas de
shortcodes de este sitio documentan ambos casos: 49 elementos svg sin procesar
en la copia Markdown de créditos y el teléfono de contacto escapado para HTML.
Ahora todo shortcode que escriba marcado dispone de su propia plantilla para la
salida Markdown. El control de calidad obligatorio también comprueba que esas
versiones no contengan HTML sin procesar ni entidades HTML, excluyendo el código
de la comprobación.
El HTML sin procesar desaparece de la página. Un bloque HTML escrito en
Markdown falta en la página compilada, aunque el original parece correcto. La
sintaxis de Gruber permite HTML en cualquier parte del texto, pero un conversor
puede rechazarlo: el ajuste unsafe de Goldmark en Hugo está desactivado de
forma predeterminada, por lo que no se representa el HTML mezclado con Markdown. GFM escapa
una lista breve de etiquetas, como script e iframe, para que se impriman
como texto. Use lo que ofrezca el generador, como un shortcode o un hook de
representación de Hugo, o active el ajuste deliberadamente y acepte lo que deja
pasar.
El analizador aprueba lo que se le indicó ignorar. Un archivo Markdown con una estructura rota supera la revisión porque markdownlint no informa de nada. Las reglas que lo habrían detectado estaban desactivadas en su configuración, sin explicación. Las reglas de desarrollo de este sitio documentan que markdownlint estuvo configurado en un archivo JSON con seis reglas desactivadas y sin comentarios; al evaluar esas seis, dos estaban ocultando defectos reales. Escriba la razón junto a cada regla desactivada, en un formato que admita comentarios, para que la siguiente persona pueda cuestionarla.
Lecturas adicionales
- Especificación CommonMark — cada regla vinculada a ejemplos de entrada y al HTML que debe producir.
- CommonMark — por qué hizo falta una especificación, cómo divergieron las implementaciones y quién la mantiene.
- Markdown, de John Gruber — la descripción original, el objetivo de diseño y el script Perl.
- Markdown: sintaxis — la explicación de la sintaxis del propio Gruber, incluida la regla del HTML en línea.
- Especificación GitHub Flavored Markdown — el dialecto de GitHub como superconjunto de CommonMark, con cada extensión identificada.
- RFC 7763: el tipo de medio text/markdown
— el tipo de medio, su
charsetobligatorio y su parámetrovariant.