Dos almohadillas (#) y un espacio delante de una línea: ## Presupuesto se convierte en un encabezado de segundo nivel. Un guion al principio de tres líneas seguidas sale como una lista de tres elementos. Markdown es exactamente eso: un texto que se sigue leyendo sin convertir y que una máquina traduce a etiquetas.
Aquí se convierte un subconjunto concreto: encabezados, negrita y cursiva, código en línea, enlaces, imágenes, listas numeradas y con viñetas, bloques de código y párrafos. Las tablas, las citas, las notas al pie y el HTML escrito a mano dentro del Markdown quedan fuera. El recuento indica cuántos bloques ha reconocido la conversión, y es la forma más rápida de ver si algo se ha quedado por el camino.
Lo que entra y lo que se queda fuera
Un encabezado se marca con hasta seis almohadillas al principio de la línea. La negrita admite dos asteriscos o dos guiones bajos a cada lado; la cursiva, solo el asterisco: un guion bajo suelto se queda tal cual. El código en línea va entre acentos graves y un bloque de código entre tres. Un enlace se escribe con el texto entre corchetes y la dirección entre paréntesis, y una imagen se escribe igual, con un signo de admiración delante: . Las listas empiezan por guion, asterisco o signo más, o por un número seguido de un punto o de un paréntesis de cierre.
Fuera quedan cuatro cosas que conviene saber antes de pegar el texto, y no después. Las tablas con barras verticales salen como un párrafo con barras verticales dentro. Las citas con el signo mayor que tampoco se convierten: el signo sale escapado dentro del párrafo, y varias líneas de cita se juntan en uno solo. Las notas al pie no se resuelven: la referencia y la definición se quedan donde estaban. Y el HTML escrito dentro del Markdown no pasa como HTML, sino como texto visible, por el motivo que se explica más abajo. A esas cuatro se añade un límite de las listas: las anidadas se aplanan, la sangría se ignora y todos los elementos salen al mismo nivel.
Markdown no tiene un estándar único
John Gruber publicó Markdown en 2004 como una descripción en prosa acompañada de un script en Perl. La descripción dejaba huecos: qué ocurre con una lista mal sangrada, cuántos espacios hacen falta, qué pasa al mezclar asteriscos y guiones bajos. Cada programa resolvió esos huecos a su manera y el mismo archivo empezó a salir distinto según dónde se abriera.
CommonMark nació en 2014 justo para eso: una especificación precisa, con cientos de casos de prueba que un conversor pasa o suspende. Sirvió, pero no zanjó la cuestión. GitHub y GitLab mantienen sus propias extensiones —tablas, listas de tareas, tachado, menciones— y esas extensiones son su dialecto, no Markdown a secas. Por eso lo útil es decir qué subconjunto se acepta, en lugar de prometer «Markdown» y dejar que el usuario lo descubra probando.
Los signos menor que, mayor que, el ampersand y las comillas dobles salen escapados
Antes de convertir nada, la entrada pasa por un escapado: esos cuatro signos se sustituyen por sus entidades HTML. Sin ese paso, una etiqueta script pegada en el Markdown viajaría intacta hasta la página donde se use el resultado, y allí sí se ejecutaría. Escapar también las comillas dobles es lo que impide que una dirección se salga del atributo href y añada un manejador de eventos al enlace. Es el agujero clásico de cualquier conversión de texto a HTML, y se tapa antes de convertir, nunca después.
La consecuencia se ve a simple vista: un div o un span escritos dentro del Markdown aparecen como texto, no como elemento. No es un fallo, es la condición para que el resultado se pueda pegar en otro sitio sin arrastrar sorpresas. Aun así, este escapado no convierte la herramienta en un saneador completo: si el texto viene de terceros, compruebe a dónde apuntan los enlaces. Una dirección que empiece por javascript: se copia tal cual al atributo href, y esa sí se ejecuta al pulsar; bórrela antes de publicar.