Sintaxis de Markdown: una guía práctica

Qué es Markdown y qué no es

Markdown se diseñó como un formato de escritura que pudiera convertirse a HTML, no como un lenguaje de descripción de páginas. No tiene concepto de fuentes, márgenes, saltos de página ni posicionamiento preciso; eso pertenece a la hoja de estilos o al conversor a PDF que consume el HTML. Eso es una ventaja: un archivo Markdown sigue siendo legible en un terminal, en una revisión de código o en un correo de texto plano.

La sintaxis original no tiene tablas, listas de tareas ni notas al pie. GitHub Flavored Markdown (GFM) añadió tablas, bloques de código delimitados con indicación de lenguaje, listas de tareas, tachado y URL con enlace automático, y la mayoría de las herramientas modernas siguen esa extensión. Si una tabla se renderiza literalmente como barras y guiones, probablemente el renderizador no admite tablas GFM, así que consulta la documentación de la herramienta antes de reescribir el contenido.

La sintaxis que usarás todos los días

La estructura de bloques se controla con líneas en blanco. Los párrafos se separan con una línea vacía; un único salto de línea suele tratarse como un espacio salvo que el renderizador admita saltos duros. Los títulos usan de una a seis almohadillas seguidas de un espacio, y el espacio es obligatorio en casi todas las implementaciones. Mantén un solo título de nivel uno por documento y construye una jerarquía en lugar de saltarte niveles.

El formato en línea usa caracteres emparejados: doble asterisco o guion bajo para negrita, un solo asterisco o guion bajo para cursiva, acentos graves para código en línea. Los enlaces son corchetes alrededor de la etiqueta seguidos de paréntesis alrededor del destino, y las imágenes añaden un signo de exclamación antes de los corchetes. Las citas empiezan con un signo mayor que, y las listas desordenadas aceptan guiones, asteriscos o signos más siempre que seas coherente dentro de una lista.

• Título: # Título, ## Sección, ### Subsección (espacio después de las almohadillas).
• Énfasis: **negrita**, *cursiva*, ***negrita y cursiva***, `código en línea`.
• Enlace: [etiqueta visible](https://example.com) e imagen: .
• Lista desordenada: un guion y un espacio por elemento; los elementos anidados necesitan una sangría coherente.
• Lista ordenada: 1. más un espacio; el renderizador renumera automáticamente, así que cada elemento puede empezar por 1.
• Cita: > antes de cada párrafo; separa bloques con una línea en blanco y otro >.
• Bloque de código: tres acentos graves, un nombre de lenguaje opcional, el código y tres acentos graves de cierre.

Tablas, código y sintaxis extendida

Una tabla GFM necesita una fila de cabecera, una fila separadora de guiones y dos puntos opcionales para la alineación, y luego filas de datos. Cada fila necesita el mismo número de barras, y una barra que falte desplaza una columna en silencio. Los bloques de código delimitados son más seguros que los bloques de código con sangría porque la delimitación sobrevive al copiar y pegar y la indicación de lenguaje activa el resaltado de sintaxis.

Las listas de tareas añaden un par de corchetes después de la viñeta: un espacio para no marcada y una x para marcada. Las notas al pie y las listas de definiciones son extensiones que varían entre renderizadores, así que evítalas cuando el documento deba sobrevivir a una conversión a PDF, a una wiki o a un correo. En caso de duda, prueba el renderizador exacto que usa tu público en lugar de suponer que todo Markdown es idéntico.

Un flujo de trabajo que mantiene legible el Markdown

Escribe pensando primero en la vista de texto plano. Mantén las líneas razonablemente cortas, separa las secciones con líneas en blanco y pon los destinos de los enlaces cerca de sus etiquetas para que el código fuente siga siendo comprensible cuando se ajuste en un editor estrecho. Usa enlaces relativos para archivos del mismo repositorio y URL absolutas para recursos externos; un enlace relativo a un archivo renombrado se convierte en un enlace roto que nadie nota hasta que un lector hace clic.

Previsualiza mientras escribes, sobre todo después de tablas, listas anidadas y bloques de código. Un editor en vivo con vista previa renderizada detecta una línea en blanco ausente antes de que llegue a una página de publicación. Cuando conviertas Markdown a HTML o PDF, mantén el código fuente bajo control de versiones: la salida renderizada es desechable, mientras que el Markdown es el documento que puedes comparar y revisar.

Dónde encaja Markdown y dónde no

Markdown es excelente para documentación, notas de versión, archivos README, actas de reuniones, artículos técnicos y todo lo que se guarde en Git. Encaja mal en maquetación para impresión, diseño con precisión de píxeles, tablas complejas con celdas combinadas o documentos que autores no técnicos necesitan editar visualmente. En esos casos escribe en un procesador de textos y exporta, o usa Markdown solo como fuente intermedia y aplica una hoja de estilos al HTML final.