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.

¿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.