# 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:

- 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](/es/credits/) 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](/es/ai-ready/)
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](/es/portfolio/wrote-50000-words-of-software-documentation/)
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](https://spec.commonmark.org/) — cada regla vinculada
  a ejemplos de entrada y al HTML que debe producir.
- [CommonMark](https://commonmark.org/) — por qué hizo falta una especificación,
  cómo divergieron las implementaciones y quién la mantiene.
- [Markdown, de John Gruber](https://daringfireball.net/projects/markdown/) — la
  descripción original, el objetivo de diseño y el script Perl.
- [Markdown: sintaxis](https://daringfireball.net/projects/markdown/syntax) — la
  explicación de la sintaxis del propio Gruber, incluida la regla del HTML en
  línea.
- [Especificación GitHub Flavored Markdown](https://github.github.com/gfm/) — el
  dialecto de GitHub como superconjunto de CommonMark, con cada extensión
  identificada.
- [RFC 7763: el tipo de medio text/markdown](https://www.rfc-editor.org/rfc/rfc7763)
  — el tipo de medio, su `charset` obligatorio y su parámetro `variant`.

<https://engineer.company/es/glossary/markdown/>
