Chuleta de Markdown

Sobre la Chuleta de Markdown

¿Qué diferencia hay entre CommonMark y GitHub Flavored Markdown?

CommonMark es la especificación inequívoca de Markdown publicada en 2014 que resuelve las docenas de casos ambiguos dejados imprecisos en la descripción original de John Gruber de 2004. GitHub Flavored Markdown (GFM) es un superconjunto estricto de CommonMark: todo lo que soporta CommonMark se soporta en GFM idénticamente, y GFM añade tablas, listas de tareas, tachado, enlaces automáticos y algunas reglas adicionales. Las funciones más recientes específicas de GitHub - avisos (> [!NOTE]), secciones plegables, código vallado con resaltado y códigos de emoji - no son estrictamente parte de GFM pero GitHub las renderiza igualmente. Esta chuleta las etiqueta como 'Extensiones GFM' por conveniencia, pero ten en cuenta que no todos los motores las renderizarán; para documentos portables usa CommonMark puro.

¿Por qué mi lista no se renderiza bien?

El problema más común de renderizado de Markdown es no dejar la línea en blanco que separa una lista del párrafo circundante. CommonMark requiere una línea en blanco antes de cualquier lista; de lo contrario el primer ítem se pega al texto previo como un solo párrafo. El segundo problema más común es la sangría de anidación: cada nivel debe sangrarse exactamente el ancho del marcador más un espacio (normalmente dos espacios para listas sin orden, tres o cuatro para ordenadas). Si un ítem anidado se niega a sangrarse, comprueba que la línea padre no termina con espacio y que usaste espacios, no tabuladores. Por último, algunos parsers antiguos no aceptan números distintos de 1 como primer ítem ordenado; CommonMark acepta cualquier número y los renderiza en orden.

¿Cómo escapo caracteres especiales de Markdown?

Pon una barra invertida antes de cualquier carácter que Markdown interpretaría: \*sin cursiva\*, \#no-encabezado, \[no-enlace\]. Los caracteres escapables son: \ ` * _ { } [ ] ( ) # + - . ! | > y ~. Fuera de ellos, una barra queda como está. El caso más sutil son los backticks dentro de código en línea: rodea tu código con una secuencia más larga de backticks, así ``código con ` dentro`` se vuelve <code>código con ` dentro</code>. Para las propias barras invertidas, duplícalas: \\. La mayoría de editores con vista previa Markdown te mostrarán al instante si el escape funcionó, así que usa una vista previa cuando dudes.

¿Son los avisos de GitHub portables a otras herramientas?

La sintaxis de avisos > [!NOTE] / [!TIP] / [!WARNING] / [!IMPORTANT] / [!CAUTION] fue introducida por GitHub a finales de 2023 y adoptada poco después por GitLab. Los renderizadores que no la implementan (la mayoría de generadores estáticos, Notion y editores Markdown antiguos) tratan el bloque como una cita normal, lo cual es elegante: el aviso sigue leyéndose correctamente, solo sin la franja de color. Si publicas tus documentos en una plataforma como MkDocs, Hugo o Jekyll, prefiere la sintaxis nativa de admonición (p. ej. !!! note ... en MkDocs Material). Para máxima portabilidad, escribe avisos como citas con texto en negrita: > **Nota:** ... que se renderiza sensatamente en todas partes.

¿Cómo escribo ecuaciones matemáticas en Markdown?

Las matemáticas en línea van entre dólares simples: $E = mc^2$. Las matemáticas en bloque entre dólares dobles en su propia línea, como $$\int_0^1 x^2 dx$$. El renderizado real depende del motor: GitHub, GitLab, Obsidian, Notion y Quarto soportan nativamente TeX/LaTeX vía KaTeX o MathJax; CommonMark clásico no. Si publicas a través de un generador estático, instala un plugin de matemáticas (rehype-katex para unified, mkdocs-material con arithmatex para MkDocs, hugo-katex para Hugo). Escapa los dólares aislados que deben aparecer como moneda con barra invertida: \$5, o el motor podría intentar entrar en modo matemático y producir resultados extraños.

¿Cómo hago una tabla en Markdown y alineo las columnas?

Las tablas usan barras verticales para separar columnas y una fila divisoria de guiones para separar el encabezado del cuerpo: | Nombre | Puntos | en la primera línea, |--------|--------| en la segunda, y luego una fila | valor | valor | por registro. Los guiones solo deben estar presentes, no alineados al texto. Para controlar la alineación de columnas, añade dos puntos a la fila divisoria: |:---| es izquierda, |:--:| es centro y |---:| es derecha. Así una fila como |:--|:-:|--:| da columnas a la izquierda, al centro y a la derecha. No necesitas barras externas, pero hacen el código más fácil de leer y copiar. Si una celda debe contener una barra vertical literal, escápala con una barra invertida como \| para que el parser no la trate como separador de columna; este es el error más común al poner código o regex dentro de una celda. Las tablas son una extensión de GFM, así que GitHub, GitLab y Obsidian las renderizan pero CommonMark estricto no.

¿Cómo añado un salto de línea en Markdown?

Markdown tiene tres formas de forzar un salto de línea dentro de un párrafo. El método clásico es terminar la línea con dos espacios finales y pulsar Enter; el problema es que el espacio final es invisible y muchos editores lo eliminan automáticamente. El método más fiable de GFM es una barra invertida al final de la línea, que es visible en el código y sobrevive al recorte de espacios. La tercera vía es la etiqueta HTML <br>, que funciona prácticamente en todos los renderizadores, incluido CommonMark estricto. Para empezar un párrafo nuevo en vez de un salto suave, deja una línea totalmente en blanco entre los dos bloques de texto; es el separador más portable de todos y lo que querrás la mayoría de las veces.

¿Qué funciones de Markdown funcionan en GitHub, GitLab y CommonMark?

Depende de la construcción, que es justo lo que muestran las insignias de compatibilidad de cada tarjeta. Negrita, cursiva, encabezados, enlaces, imágenes, citas, listas y código vallado son CommonMark básico y se renderizan igual en todas partes. Tablas, listas de tareas, tachado y enlaces de URL desnuda son extensiones de GFM: GitHub, GitLab y Obsidian los soportan, pero CommonMark estricto no. Las notas al pie y las matemáticas TeX/LaTeX se renderizan en GitHub, GitLab y Obsidian pero no en CommonMark puro. Los avisos de GitHub (> [!NOTE]) funcionan en GitHub, GitLab y Obsidian (Obsidian tiene avisos nativos) pero se degradan a una cita simple en otros lugares. Las @menciones y referencias #issue son específicas de GitHub. Las listas de definiciones (término / : definición) son una función de Markdown Extra / pandoc y no se renderizan en ninguna de las cuatro. Para documentos que deben sobrevivir a cualquier flujo, activa "Solo portable" para filtrar la hoja al subconjunto seguro en CommonMark.

¿Por qué esta chuleta carga mucho más rápido que otros sitios de documentación?

Tres razones. Primero, cada tarjeta se renderiza en el servidor como HTML estático; no hay parser Markdown del lado del cliente, ni bundles de Mermaid, ni resaltado de sintaxis en JavaScript: los bytes que ves en pantalla son los que envió el servidor. Segundo, la búsqueda usa un filtro vanilla con querySelectorAll sobre unas pocas docenas de tarjetas, así que incluso en un móvil modesto cada pulsación actualiza el DOM en menos de un milisegundo. Tercero, la página tiene caché agresiva en la infraestructura de WuTools: el HTML está cacheado 10 días, el pequeño JS del filtro un año, y los iconos SVG también. Una vez que un visitante recurrente tiene la página en caché, la chuleta aparece prácticamente en el tiempo que tarda el navegador en pintar un frame.