Saltar al contenido
Engineer
Menú
Diseño
Español

Engineer / Glosario

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 servidor

Un 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.md

Unas 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

Contacto

¿Aún está definiendo lo que necesita?

Cuéntenos qué está fallando o qué intenta construir. Le diremos qué haría falta, cuánto costaría aproximadamente y si somos las personas adecuadas.

Desde 1.400 DKK por hora, sin IVA; y un precio por hora menor en una contratación más larga.

welcome@engineer.company +45 50 10 61 84 Copenhague, Dinamarca