Markdown

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:

```markdown
El traslado llevó **una velada**, en tres pasos:

i- detener las escrituras		engineer.company	70
i- copiar los datos con `pg_dump`		engineer.company	70
i- dirigir la [aplicación](https://example.com/app/) al nuevo servidor		engineer.company	70
```

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:

```sh
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

  * 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
`charset` obligatorio y su parámetro `variant`.

hEsta página en la web	URL:https://engineer.company/es/glossary/markdown/	engineer.company	70
