51. Compatibilidad {#51-compatibilidad}

Un mismo documento Markdown puede verse diferente en GitHub, GitLab, VS Code, Obsidian, Jekyll, MkDocs o un navegador. La causa no es que “Markdown esté roto”, sino que cada herramienta implementa un dialecto, activa unas extensiones y aplica su propio CSS, su sanitización y sus convenciones de enlaces.

51.1 Por qué cambia el renderizado {#511-por-qué-cambia-el-renderizado}

51.2 Núcleo común {#512-núcleo-común}

La tabla siguiente resume el comportamiento habitual; la configuración concreta puede cambiar el resultado. Leyenda: Sí = soportado por defecto; Ext. = requiere extensión, plugin o configuración; No = no soportado; Varía = depende de la versión o del tema.

51.3 Extensiones y funciones de plataforma {#513-extensiones-y-funciones-de-plataforma}

“GitHub” se refiere a github.com, no solo a la especificación GFM. “GitLab” incluye GitLab.com y las versiones autogestionadas, que pueden variar. “Jekyll” usa Kramdown por defecto, pero puede configurarse con GFM. “MkDocs” usa Python-Markdown y depende de las extensiones declaradas en mkdocs.yml.

51.4 Detalles por plataforma {#514-detalles-por-plataforma}

GitHub

• Usa GFM, definido como superconjunto de CommonMark, más funciones de la plataforma.
• Soporta tablas, listas de tareas, tachado, autolinks, notas al pie, matemáticas, Mermaid, alertas (> [!NOTE]), menciones y referencias a issues.
• Sanea el HTML: elimina scripts, manejadores de eventos y etiquetas peligrosas.
• Las rutas relativas se resuelven respecto al archivo dentro del repositorio.
• Un archivo .mdx no se renderiza como MDX: se muestra como texto o código; GitHub no compila JSX.
• Documentación: https://docs.github.com/en/get-started/writing-on-github

GitLab

• Usa GitLab Flavored Markdown, inspirado en GFM pero con diferencias.
• Soporta tablas, listas de tareas, tachado, notas al pie, definiciones, alertas, Front Matter, TOC, matemáticas, Mermaid y referencias a issues/MRs.
• Sanea el HTML y aplica sus propias reglas de seguridad.
• Algunas funciones cambian entre versiones y ediciones (CE/EE).
• Documentación: https://docs.gitlab.com/user/markdown/

Visual Studio Code

• La previsualización integrada usa markdown-it y extensiones propias; no es idéntica a GitHub.
• Opciones como markdown.preview.breaks alteran el tratamiento de los saltos de línea.
• Mermaid, matemáticas avanzadas y exportación suelen requerir extensiones.
• Es excelente para editar, pero conviene validar en el renderizador final.
• Documentación: https://code.visualstudio.com/docs/languages/markdown

Obsidian

• Usa un dialecto propio con wikilinks, embeds, callouts, etiquetas y propiedades.
• Los enlaces [[nota]] y los callouts > [!note] no son Markdown estándar.
• Permite HTML y plugins de la comunidad, con los riesgos que ello implica.
• Es ideal para notas personales, no necesariamente para documentación portable.
• Ayuda: https://help.obsidian.md/

Jekyll

• Generador de sitios estáticos en Ruby, usado por GitHub Pages.
• Por defecto utiliza Kramdown; se puede configurar markdown: GFM en _config.yml.
• Requiere Front Matter para procesar páginas y publicaciones.
• Las extensiones (Mermaid, matemáticas, admoniciones) dependen de plugins y del tema.
• Documentación: https://jekyllrb.com/docs/configuration/markdown/

MkDocs

• Generador de documentación en Python; usa Python-Markdown.
• Las tablas, notas al pie, definiciones, admoniciones, matemáticas y Mermaid requieren extensiones o plugins.
• Material for MkDocs añade componentes y sintaxis propias (admoniciones, pestañas, botones).
• El tema controla la navegación, el índice y el aspecto.
• Documentación: https://squidfunk.github.io/mkdocs-material/

CommonMark

• Define el núcleo estricto: párrafos, títulos, énfasis, listas, citas, código, enlaces, imágenes y HTML.
• No incluye tablas, listas de tareas, tachado, notas al pie ni Mermaid.
• Es la base más portable para contenido que debe funcionar en muchos sistemas.
• Especificación: https://spec.commonmark.org/

Navegadores

• Un navegador no interpreta Markdown: recibe HTML ya renderizado.
• Las diferencias visuales provienen del CSS, las fuentes, el tamaño de ventana y las capacidades del navegador.
• HTML5 es un estándar independiente; no debe confundirse con Markdown.
• Especificación HTML: https://html.spec.whatwg.org/

Otros renderizadores

51.5 Estándar frente a extensión {#515-estándar-frente-a-extensión}

51.6 Cómo escribir Markdown portable {#516-cómo-escribir-markdown-portable}

1. Usa el núcleo CommonMark para el contenido esencial.
2. Evita HTML salvo que sea imprescindible y esté permitido.
3. No dependas de extensiones para información crítica: si usas una tabla, ofrece una lista equivalente cuando la portabilidad sea prioritaria.
4. Usa enlaces relativos y comprueba cómo se resuelven en el destino.
5. No confíes en los IDs automáticos de los encabezados: si necesitas anclas estables, usa un ID explícito cuando la herramienta lo permita o mantén títulos estables.
6. Especifica el lenguaje en los bloques de código.
7. Prueba en el renderizador final, no solo en el editor.
8. Documenta las extensiones que usa el proyecto (Mermaid, matemáticas, alertas).
9. Mantén el Front Matter solo si el SSG lo necesita.
10. Evita sintaxis específica de un editor en documentos compartidos.

51.7 Cómo comprobar la compatibilidad {#517-cómo-comprobar-la-compatibilidad}