GFM frente a CommonMark frente a Pandoc Markdown: comparación de sintaxis

Markdown parece ser un solo lenguaje hasta que el mismo archivo se renderiza de forma diferente en GitHub, Hugo, Obsidian o Pandoc. Y el problema no es que Markdown sea poco fiable.

Sino que “Markdown” describe una familia de sintaxis, analizadores y funciones de plataforma relacionadas, en lugar de un único formato universal de documento. CommonMark define un núcleo portátil y preciso, GitHub Flavored Markdown añade funciones útiles para la colaboración en software, y Pandoc Markdown expande el lenguaje hasta convertirlo en un formato serio para la redacción de documentos.

La elección entre ellos depende de dónde debe renderizarse el documento. Un archivo README, una entrada de blog de Hugo y un artículo académico tienen requisitos diferentes. Esta comparación es parte del panorama más amplio de herramientas de documentación y cubre los dialectos formales, las extensiones específicas de la plataforma y las reglas prácticas de portabilidad para que puedas elegir la sintaxis adecuada para tu entorno objetivo. Para una referencia rápida de sintaxis, la hoja de referencia de Markdown cubre los elementos esenciales de formato.

Markdown no es un solo lenguaje

La sintaxis original de Markdown era intencionalmente pequeña y especificada de forma laxa. Eso la hacía fácil de leer e implementar, pero diferentes analizadores comenzaron a interpretar las entradas ambiguas de manera distinta.

CommonMark se creó para definir reglas de análisis consistentes para las estructuras fundamentales de Markdown. GitHub Flavored Markdown, generalmente llamado GFM, se basa en ese fundamento con varias ampliamente utilizadas extensiones.

Pandoc Markdown toma un enfoque diferente. En lugar de permanecer como una pequeña sintaxis orientada a la web, añade funciones documentales como citas, metadatos, notas al pie, listas de definición, atributos y notación matemática.

Una relación simplificada se ve así:

Esta jerarquía es útil, pero no es una herencia exacta en todas las implementaciones. Cada renderizador puede habilitar, deshabilitar o añadir sintaxis de forma independiente.

La respuesta corta

Usa sintaxis compatible con CommonMark cuando la portabilidad sea lo más importante.

Usa GFM cuando escribas archivos README, solicitudes de extracción (pull requests), plantillas de problemas y documentación técnica destinada principalmente a plataformas compatibles con GitHub.

Usa Pandoc Markdown cuando el documento fuente debe convertirse en PDF, DOCX, EPUB, LaTeX, diapositivas o un artículo académico con citas y metadatos.

Para un blog técnico de Hugo, usa el núcleo CommonMark más las extensiones de Goldmark que tu sitio habilite explícitamente. No asumas que todas las funciones visibles en GitHub funcionarán solo porque Hugo se describe como compatible con GFM.

Opinión fundamentada: si solo recuerdas una regla para un blog técnico de Hugo, trata CommonMark más tablas y listas de tareas de estilo GFM como el valor predeterminado, y trata todo lo demás — notas al pie, matemáticas, avisos, atributos de encabezados — como una extensión explícita y probada, en lugar de un valor predeterminado asumido. Este único hábito previene la mayoría de los fallos de portabilidad descritos a continuación.

CommonMark: El núcleo portátil

CommonMark es una especificación formal para el lenguaje básico de Markdown. Su principal contribución no es una gran colección de funciones, sino un análisis consistente.

Define cómo los analizadores deben interpretar:

• Párrafos
• Encabezados ATX y Setext
• Citas en bloque
• Listas ordenadas y desordenadas
• Bloques de código con delimitadores y con sangría
• Énfasis y énfasis fuerte
• Enlaces e imágenes
• Enlaces de estilo referencia
• Código en línea
• Separadores temáticos
• Bloques de HTML sin procesar
• Saltos de línea duros y suaves

Un documento CommonMark puede seguir teniendo un comportamiento diferente en la capa de presentación. CSS, resaltado de sintaxis, anclas de encabezados, saneamiento de HTML y políticas de enlace están fuera de las reglas de análisis del núcleo.

CommonMark debe considerarse, por lo tanto, como una línea de base estructural fiable, no como una promesa de que cada renderizador producirá una página idéntica.

Un ejemplo portátil de CommonMark

# Despliegue del servicio

El servicio expone una pequeña API HTTP.

## Requisitos

- Linux
- Docker
- 8 GB de memoria

## Iniciar el servicio

```bash
docker compose up -d
```

Consulta la [guía de configuración](configuration.md) para obtener más detalles.

Este tipo de documento funciona en casi todos los entornos modernos de Markdown. Utiliza encabezados, párrafos, listas, código delimitado y enlaces ordinarios sin depender de extensiones específicas de un dialecto.

GitHub Flavored Markdown: CommonMark para proyectos de software

GitHub Flavored Markdown es un dialecto formal basado en CommonMark. Preserva el modelo de análisis de CommonMark y añade funciones comúnmente necesarias en la documentación de repositorios y la colaboración.

La especificación formal de GFM añade:

• Tablas con barras verticales
• Elementos de lista de tareas
• Tachado
• Autolinks extendidos
• Restricciones alrededor de algunas etiquetas de HTML sin procesar

Estas extensiones son ahora tan comunes que muchos usuarios piensan que forman parte del Markdown estándar. No forman parte del núcleo de CommonMark.

Tablas en GFM

| Backend | Mejor uso |
|---|---|
| Ollama | Experimentos locales |
| vLLM | Inferencia compartida |
| SGLang | Cargas de trabajo estructuradas |

Un analizador estricto de CommonMark está permitido para tratar esto como texto de párrafo ordinario. Un analizador compatible con GFM lo reconoce como una tabla. Para una visión más profunda de la sintaxis de tablas y las opciones de alineación, consulta Tablas en Markdown.

Listas de tareas en GFM

- [x] Instalar Docker
- [x] Descargar el modelo
- [ ] Añadir monitoreo

La sintaxis de listas de tareas es útil en problemas, solicitudes de extracción y documentación de proyectos. Fuera de un renderizador de soporte, puede aparecer como una lista ordinaria que contiene corchetes literales.

Tachado en GFM

Usa el nuevo ~~antiguo~~ endpoint.

El tachado está ampliamente soportado, pero sigue siendo una extensión y no sintaxis portable de CommonMark.

Autolinks en GFM

GFM reconoce más texto similar a URL y similar a correo electrónico sin requerir corchetes angulares o sintaxis de enlace explícita.

Visita https://example.com/docs para obtener más detalles.

En CommonMark estricto, los autolinks explícitos usan corchetes angulares:

<https://example.com/docs>

La forma explícita es más segura cuando un documento debe viajar a través de procesadores de Markdown desconocidos.

GitHub.com soporta más que el GFM formal

Una fuente frecuente de confusión es el supuesto de que cada función de Markdown visible en GitHub pertenece a la especificación de GFM.

No es así.

GitHub.com añade procesamiento a nivel de plataforma y funciones alrededor del analizador GFM. Dependiendo del contexto, GitHub puede soportar:

• Expresiones matemáticas
• Diagramas Mermaid
• Avisos
• Referencias a problemas y solicitudes de extracción
• Menciones de usuarios y equipos
• Referencias a commits
• Shortcodes de emojis
• Secciones HTML plegables
• Vistas previas de color
• Enlaces relativos al repositorio
• Anclas de encabezado automáticas

Algunas de estas funciones son extensiones de sintaxis. Otras son comportamiento de posprocesamiento o integraciones con datos de GitHub.

Esta distinción importa porque otro renderizador puede reclamar con precisión la compatibilidad con GFM sin implementar el renderizador matemático de GitHub, la integración de Mermaid, las referencias de problemas o el estilo de avisos.

Diagramas Mermaid en GitHub

GitHub renderiza un bloque de código delimitado marcado como mermaid como un diagrama:

```mermaid
flowchart LR
    A[Markdown] --> B[Diagrama renderizado]
```

Un renderizador GFM genérico puede mostrar el mismo bloque como código fuente resaltado. El Markdown permanece válido, pero el renderizado enriquecido es específico de la plataforma. Para una introducción práctica a la sintaxis de Mermaid, consulta la Guía rápida de Diagramas Mermaid.

Expresiones matemáticas en GitHub

GitHub soporta expresiones matemáticas en línea y en bloque usando delimitadores de dólar y formas de escape adicionales.

El tamaño de la caché es aproximadamente $2nlhd$ bytes.

$$
C = 2nlhd
$$

Las matemáticas no forman parte del GFM formal. Mover este contenido a otro renderizador requiere una extensión matemática compatible como KaTeX, MathJax o soporte matemático de Pandoc.

Avisos en GitHub

GitHub soporta citas en bloque de estilo aviso como:

> [!WARNING]
> Cambiar esta configuración borra la caché.

En GitHub, esto puede aparecer como un aviso con estilo. En un renderizador CommonMark plano, generalmente aparece como una cita en bloque ordinaria que contiene [!WARNING].

Ese comportamiento de respaldo es legible, lo que hace que los avisos de GitHub sean menos peligrosos que las extensiones que desaparecen por completo. Todavía no son elementos de presentación portables.

Pandoc Markdown: Markdown como lenguaje de documentos

Pandoc Markdown está diseñado para la conversión de documentos en lugar de un sitio web particular. Utiliza Markdown como sintaxis de origen para producir HTML, PDF, DOCX, EPUB, LaTeX, presentaciones y otros formatos.

Su lector de Markdown predeterminado incluye un gran conjunto de extensiones. Las capacidades importantes incluyen:

• Bloques de metadatos YAML
• Notas al pie
• Citas
• Múltiples formatos de tablas
• Listas de definición
• Notación matemática
• Identificadores y atributos de encabezados
• Atributos de bloques de código
• Divisiones delimitadas
• Spanes con corchetes
• Superíndice y subíndice
• Tachado
• Bloques de línea
• Listas de ejemplos numeradas
• LaTeX sin procesar
• HTML sin procesar
• Numeración automática de secciones
• Procesamiento de bibliografía

Pandoc Markdown es mucho más expresivo que CommonMark o el GFM formal. Esa expresividad lo hace poderoso para la publicación, pero menos seguro como formato de intercambio.

Notas al pie en Pandoc

Markdown tiene varios dialectos incompatibles.[^dialects]

[^dialects]: CommonMark, GFM y Pandoc Markdown son tres
    ejemplos importantes.

La sintaxis de notas al pie está soportada por muchas herramientas modernas, pero no forma parte de CommonMark o del GFM formal.

GitHub actualmente renderiza notas al pie en varios contextos de contenido, pero eso es una función de la plataforma de GitHub y no una garantía formal de GFM. Un renderizador que reclame solo compatibilidad con CommonMark o GFM puede no soportarlas.

Citas en Pandoc

PagedAttention mejora la gestión de memoria de la caché KV
[@kwon2023pagedattention].

Con un archivo de bibliografía y un estilo de citación, Pandoc puede resolver esto en una citación académica formateada y una bibliografía.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

La sintaxis de citación permanece legible en un renderizador no soportado, pero no se convertirá en una referencia formateada sin Pandoc u otro procesador de citación compatible. La flexibilidad del lector de Pandoc también sustenta flujos de trabajo de conversión en la dirección opuesta — consulta convertir documentos de Word a Markdown para un ejemplo práctico de uso del dialecto extendido de Pandoc como formato intermedio.

Listas de definición en Pandoc

CommonMark
: Una especificación precisa para el Markdown central.

GFM
: Un dialecto basado en CommonMark con extensiones orientadas al software.

Pandoc Markdown
: Un formato de redacción extendido para la conversión de documentos.

Las listas de definición son útiles en manuales, glosarios y libros técnicos. Normalmente se degradan mal en renderizadores que no las soportan porque las líneas de dos puntos permanecen visibles como texto plano.

Atributos de encabezados en Pandoc

## Configuración de caché {#cache-config .deployment}

Pandoc interpreta las llaves como un identificador y una lista de clases explícitos. Muchos otros renderizadores de Markdown muestran el texto de atributos directamente en el encabezado.

Este es uno de los ejemplos más claros de sintaxis útil que no debe colocarse en un documento esperado para renderizarse en cualquier lugar.

Divisiones delimitadas en Pandoc

::: warning
Cambiar esta opción reinicia el servidor.

Pandoc convierte esto en una división estructural con una clase. Las plantillas, CSS, filtros o escritores de salida pueden decidir cómo debe aparecer esa estructura.

La mayoría de los renderizadores CommonMark y GFM no reconocen la delimitación. Muestran los dos puntos y el contenido como texto ordinario.

CommonMark vs GFM vs Pandoc Markdown

La siguiente matriz describe los dialectos formales, no cada función añadida por GitHub.com, Hugo, Obsidian, GitLab u otra plataforma.

La palabra “No” no significa que una plataforma no pueda soportar nunca la función. Significa que la función no está garantizada por la especificación formal de ese dialecto.

¿Qué sintaxis funciona en GitHub?

Para archivos README, problemas, solicitudes de extracción, discusiones y wikis, GFM es la línea de base natural.

Generalmente puedes usar:

• Sintaxis CommonMark
• Tablas
• Listas de tareas
• Tachado
• Autolinks extendidos
• Cercos de código con resaltado de sintaxis
• Referencias específicas de GitHub
• Matemáticas soportadas por GitHub
• Diagramas soportados por GitHub
• Avisos de GitHub
• Notas al pie donde estén soportadas por la superficie de contenido

El riesgo de portabilidad comienza cuando GitHub realiza un renderizado adicional más allá del GFM formal. Los diagramas Mermaid, la notación matemática, las referencias de problemas y la presentación de avisos pueden no sobrevivir fuera de GitHub.

Para archivos de repositorio que también se publican en otro lugar, prueba la fuente en el segundo renderizador en lugar de tratar la vista previa de GitHub como autoritaria.

¿Qué sintaxis funciona en Hugo?

Hugo usa Goldmark como su renderizador de Markdown predeterminado. Goldmark se ajusta a CommonMark y proporciona extensiones compatibles con partes importantes de GFM.

En una configuración típica de Hugo, lo siguiente funciona bien:

• Estructura CommonMark
• Bloques de código delimitados
• Tablas con barras verticales
• Tachado
• Listas de tareas
• IDs de encabezado automáticos
• Resaltado de sintaxis
• Notas al pie cuando la extensión está habilitada
• Listas de definición cuando está habilitado
• Sustituciones tipográficas cuando está habilitado

Hugo también añade funciones fuera de Markdown a través de:

• Front matter
• Shortcodes
• Render hooks
• Recursos de página
• Funciones de referencia interna
• Procesamiento de plantillas
• Configuración del sitio

Estas funciones de Hugo no viajan con el archivo de Markdown. Para un ejemplo práctico de despliegue de Hugo, consulta Desplegar Hugo en AWS S3.

El Front Matter de Hugo no es contenido de Markdown

Una página de Hugo comúnmente comienza con metadatos YAML, TOML o JSON:

---
title: "Compatibilidad de Markdown"
description: "Comparar dialectos y renderizadores de Markdown."
date: 2026-07-31
tags:
  - Markdown
  - documentación
---

Pandoc también puede reconocer bloques de metadatos YAML, pero interpreta los campos según sus propias plantillas y escritores. GitHub normalmente muestra el bloque como una sección similar a YAML o lo trata como metadatos de repositorio solo en sistemas específicos.

La misma sintaxis puede reconocerse por lo tanto en más de una herramienta sin tener las mismas semánticas.

HTML sin procesar en Hugo

Goldmark no renderiza HTML sin procesar potencialmente inseguro por defecto en una configuración estándar de Hugo.

Un bloque como:

<div class="notice">
  Reinicia el servicio después de cambiar este valor.
</div>

puede omitirse a menos que el renderizado de HTML sin procesar esté habilitado o el contenido esté implementado a través de un shortcode o un render hook.

Para un blog técnico controlado, habilitar HTML sin procesar puede ser razonable. Aún así, hace que la fuente sea menos portable y debe ser una decisión deliberada a nivel de sitio.

Mermaid en Hugo

Un bloque mermaid delimitado sigue siendo solo un bloque de código a menos que el tema de Hugo, el render hook, el shortcode o la canalización de JavaScript lo transforme en un diagrama.

GitHub y Hugo pueden por lo tanto aceptar código fuente de Mermaid idéntico usando mecanismos de renderizado completamente diferentes.

¿Qué sintaxis funciona en Pandoc?

Pandoc puede leer varios dialectos de Markdown explícitamente:

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

Esta es una de las funciones de portabilidad más útiles de Pandoc. El operador puede indicarle a Pandoc qué dialecto usa la fuente en lugar de depender de una extensión de archivo .md vaga.

Pandoc también te permite habilitar o deshabilitar extensiones individuales:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

O comenzar desde un formato más estrecho y añadir una función:

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

Puedes inspeccionar las extensiones disponibles con:

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

Este modelo de extensiones es poderoso, pero significa que “Pandoc Markdown” no siempre es una configuración fija. Los comandos de construcción y los archivos de valores predeterminados forman parte de la especificación del documento.

¿Qué sintaxis funciona en Obsidian?

Obsidian almacena notas como archivos de Markdown, pero su modelo de redacción incluye varias funciones específicas de la aplicación.

Ejemplos comunes incluyen:

• Enlaces wiki
• Notas incrustadas
• Archivos incrustados
• Avisos (Callouts)
• Referencias de bloque
• Etiquetas
• Propiedades
• Resaltado
• Comentarios
• Consultas Dataview de plugins
• Enlaces URI específicos de la aplicación

Un enlace wiki como:

[[Compatibilidad de Markdown]]

es significativo dentro de un bóveda de Obsidian. GitHub, CommonMark y un lector Pandoc predeterminado normalmente lo muestran como texto con corchetes literal.

Una incrustación es aún más específica de la aplicación:

![[tabla-de-compatibilidad]]

El contenido referenciado no está presente en el archivo en sí. Exportar o publicar la nota requiere por lo tanto un paso de expansión que resuelva la incrustación.

Obsidian es un buen ejemplo de por qué el almacenamiento en archivos .md no garantiza la portabilidad de Markdown. Para una visión práctica de Obsidian como herramienta de gestión del conocimiento, consulta Obsidian para la Gestión Personal del Conocimiento.

¿Qué sintaxis funciona en GitLab?

GitLab Flavored Markdown usa CommonMark como su núcleo e incluye funciones GFM como tablas y listas de tareas. Luego añade comportamiento específico de GitLab, incluyendo referencias cruzadas, notación matemática, diagramas y otras funciones de colaboración.

Un README escrito en GFM conservador suele moverse entre GitHub y GitLab sin daños mayores.

Las integraciones de plataforma no viajan de forma tan fiable. Las referencias de problemas, menciones de usuarios, diagramas, el manejo de matemáticas y la sintaxis de bloques especiales pueden comportarse de manera diferente incluso cuando el Markdown básico permanece legible.

Matriz de soporte de plataforma

Esta matriz describe el comportamiento predeterminado común. Los temas, plugins, extensiones y la configuración pueden cambiar celdas individuales.

“Sí” todavía no garantiza HTML o presentación visual idénticos. Significa que el entorno reconoce la función general.

Sintaxis que generalmente es segura en todas partes

El subconjunto más seguro y portable incluye:

• Encabezados ATX usando #
• Párrafos ordinarios
• Líneas en blanco entre bloques
• - para listas desordenadas
• 1. para listas ordenadas
• Bloques de código delimitados usando comillas al revés
• Código en línea usando comillas al revés
• Énfasis usando *texto*
• Énfasis fuerte usando **texto**
• Enlaces ordinarios
• Imágenes ordinarias
• Citas en bloque
• Separadores temáticos
• Autolinks explícitos con corchetes angulares

Un documento intencionalmente conservador podría verse así:

# Guía de despliegue

Esta guía explica cómo desplegar el servicio.

## Requisitos

- Docker
- Linux
- Una GPU compatible

## Configuración

Crea un archivo llamado `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

Para más información, consulta la [referencia de configuración](config.md).

> Haz una copia de seguridad de los datos existentes antes de actualizar.

Esta sintaxis viaja bien porque no depende de tablas, notas al pie, atributos, avisos o procesamiento de plataforma.

Sintaxis que comúnmente se rompe

Los problemas de portabilidad tienden a agruparse alrededor de un pequeño número de funciones.

Tablas con barras verticales

Las tablas con barras verticales están bien soportadas por herramientas orientadas a GFM, pero no por CommonMark estricto.

Una tabla puede degradarse en texto ilegible cuando pasa a través de un analizador que no la reconoce. Para documentos altamente portables, considera listas cortas o HTML semántico generado durante un paso de construcción.

Notas al pie

La sintaxis de notas al pie se ha vuelto común, pero permanece como una extensión.

Diferentes herramientas pueden:

• Soportar solo un formato de nota al pie
• Colocar las notas al pie de manera diferente
• Generar identificadores diferentes
• Rechazar notas al pie de múltiples párrafos
• Renderizar la fuente literalmente

Usa notas al pie cuando el flujo de trabajo de publicación sea conocido. Evita depender de ellas en archivos README que deben renderizarse en sistemas arbitrarios.

IDs y atributos de encabezados

Esta sintaxis de Pandoc no es portable:

## Instalación {#installation .procedure}

Usa un encabezado ordinario y deja que el renderizador genere su propia ancla cuando la portabilidad importe.

Evita también codificar en rígido enlaces a IDs de encabezado generados automáticamente a menos que todos los objetivos usen las mismas reglas de slugificación.

Avisos y alertas

GitHub, Obsidian, GitLab, MkDocs, Docusaurus y temas de Hugo pueden soportar todos bloques similares a avisos, pero a menudo usan sintaxis diferente.

Un respaldo portable es una cita en bloque ordinaria:

> Advertencia: Haz una copia de seguridad de la base de datos antes de actualizar.

Es menos impresionante visualmente, pero preserva el significado en todas partes.

Enlaces wiki

Los enlaces wiki son concisos dentro de herramientas de gestión del conocimiento:

[[Caché KV]]

Son una sintaxis de intercambio pobre porque la ruta objetivo, el nombre del archivo, las reglas de encabezado y el comportamiento de resolución pertenecen a la aplicación.

Usa enlaces de Markdown estándar en contenido destinado a publicación:

[Caché KV](kv-cache.md)

HTML sin procesar

El HTML sin procesar es la solución habitual cuando Markdown no puede expresar un diseño. También es un fallo común de portabilidad y seguridad.

Un renderizador puede:

• Eliminar el HTML
• Escaparlo
• Saneamiento elementos seleccionados
• Permitir bloques pero no elementos en línea
• Rechazar el análisis de Markdown dentro del HTML
• Pasarlo sin cambios solo en modo de confianza

Usa HTML sin procesar solo cuando el objetivo de publicación esté controlado.

Notación matemática

Las matemáticas delimitadas por dólar son populares pero no interpretadas universalmente.

La fuente:

La complejidad es $O(n^2)$.

puede convertirse en:

• Matemáticas renderizadas
• Texto ordinario con signos de dólar
• Énfasis incorrecto
• Entrada para un analizador matemático diferente

Elige una canalización matemática única y pruébala en cada entorno objetivo.

Bloques de diagramas Mermaid y otros

Un cerco de código Mermaid es sintácticamente seguro porque los renderizadores no soportados normalmente lo muestran como código.

El resultado semántico sigue siendo diferente. Los lectores pueden ver un diagrama de arquitectura renderizado en GitHub y el código fuente de Mermaid en bruto en otro entorno.

Esta es una degradación elegante, no una compatibilidad verdadera.

Las tres capas de compatibilidad de Markdown

Ayuda separar la compatibilidad en tres capas.

Capa 1: Compatibilidad de análisis

¿El analizador reconoce la estructura?

Los ejemplos incluyen encabezados, tablas, notas al pie y divisiones delimitadas.

Capa 2: Compatibilidad de transformación

¿La plataforma aplica un procesamiento adicional?

Los ejemplos incluyen:

• Renderizado de Mermaid
• Resolución de citas
• Expansión de enlaces wiki
• Vinculación de números de problema
• Procesamiento de shortcodes
• Generación de una tabla de contenido

Capa 3: Compatibilidad de presentación

¿El resultado se ve y se comporta apropiadamente?

Los ejemplos incluyen:

• Estilización de tablas
• Resaltado de sintaxis
• Colores de alerta
• Anclas de encabezados
• Imágenes responsivas
• Colocación de notas al pie
• Fuentes matemáticas

Dos plataformas pueden analizar sintaxis idéntica produciendo una presentación sustancialmente diferente.

Un mejor modelo de portabilidad

En lugar de preguntar si un archivo es “Markdown válido”, pregunta cuatro preguntas más estrechas:

1. ¿En qué dialecto está escrito la fuente?
2. ¿Qué analizador lo lee?
3. ¿Qué extensiones están habilitadas?
4. ¿Qué transformaciones de plataforma se ejecutan después?

Por ejemplo:

Dialecto: CommonMark más tablas GFM
Analizador: Goldmark
Extensiones: tablas, tachado, listas de tareas, notas al pie
Plataforma: Hugo
Procesamiento adicional: render hooks y JavaScript de Mermaid

Esa descripción es mucho más útil que decir “el sitio usa Markdown”.

Eligiendo un dialecto por caso de uso

Archivos README

Usa GFM.

Los archivos README se benefician de:

• Tablas
• Listas de tareas
• Código delimitado
• Autolinks
• Tachado
• Referencias de GitHub

Evita la dependencia excesiva de funciones exclusivas de GitHub cuando el repositorio se refleja en GitLab, se renderiza en un registro de paquetes o se incluye en documentación generada.

Artículos técnicos de Hugo

Usa Markdown compatible con CommonMark con un conjunto documentado de extensiones de Goldmark.

Las tablas, los cercos de código, las notas al pie y Mermaid pueden ser razonables porque controlas el flujo de trabajo de construcción. Prefiere los shortcodes de Hugo o los render hooks sobre incrustar grandes cantidades de HTML sin procesar.

Mantén la sintaxis específica de Hugo aislada y fácil de encontrar.

Documentos académicos

Usa Pandoc Markdown.

Las citas, el procesamiento de bibliografía, las notas al pie, los metadatos, la notación matemática, las referencias cruzadas y la conversión a PDF o DOCX justifican la portabilidad reducida.

Almacena el comando de Pandoc, el archivo de valores predeterminados, los filtros, la bibliografía y las plantillas junto a la fuente. El archivo fuente por sí solo no describe completamente la construcción.

Libros y documentación extensa

Pandoc Markdown suele ser la opción más fuerte de las tres cuando importan múltiples formatos de salida.

Las listas de definición, las citas, los atributos, los metadatos y las transformaciones estructuradas se vuelven más importantes a medida que crece la complejidad del documento.

Para documentación solo para web alojada en un repositorio de Git, GFM o un generador de documentación basado en CommonMark puede permanecer más simple.

Notas y bases de conocimiento personal

Usa la sintaxis nativa de la aplicación de notas seleccionada cuando las funciones de la aplicación aportan valor real.

Los enlaces wiki, las incrustaciones y los avisos de Obsidian son útiles dentro de una bóveda. Trata la exportación como un proceso de compilación en lugar de asumir que los archivos en bruto son ya publicaciones portables.

Documentación compartida entre sistemas desconocidos

Usa un subconjunto conservador de CommonMark.

Evita:

• Enlaces wiki
• Alertas de plataforma
• Atributos de encabezados
• Citas
• HTML sin procesar
• Contenedores personalizados
• Incrustaciones de aplicación
• Shortcodes

La portabilidad generalmente requiere renunciar a funciones de conveniencia.

Reglas prácticas para Markdown portable

Comienza con la estructura de CommonMark

Usa CommonMark para el esqueleto del documento:

• Encabezados
• Párrafos
• Listas
• Enlaces
• Imágenes
• Citas en bloque
• Bloques de código

Esto asegura que el significado principal sobreviva incluso cuando las extensiones opcionales fallen.

Añade funciones GFM deliberadamente

Las tablas y las listas de tareas son razonables cuando todos los objetivos importantes las soportan.

No asumas que “la mayoría de las herramientas soportan GFM” sin probar el objetivo exacto. Algunos reclaman compatibilidad con GFM mientras habilitan solo extensiones seleccionadas.

Aísla las extensiones de plataforma

Mantén la sintaxis específica de la plataforma en bloques claramente identificables.

Por ejemplo, centraliza los shortcodes de Hugo, las citas de Pandoc o las incrustaciones de Obsidian en lugar de esparcirlas por cada párrafo.

El aislamiento facilita la conversión posterior.

Prefiere la degradación elegante

Un bloque Mermaid se degrada en código fuente legible. Un aviso de GitHub se degrada en una cita en bloque.

Una incrustación wiki puede degradarse en un nombre de archivo no explicado, mientras que una división delimitada de Pandoc puede exponer la puntuación alrededor del contenido.

Elige extensiones cuyo respaldo permanezca comprensible.

No dependas de los IDs de encabezado generados automáticamente

Los algoritmos de ancla de encabezados difieren entre GitHub, Hugo, Pandoc y generadores de documentación.

Para enlaces entre documentos, usa IDs explícitos soportados por el renderizador solo cuando el flujo de trabajo objetivo esté controlado. De lo contrario, enlaza al documento en lugar de un fragmento generado.

Mantén la configuración de construcción con el contenido

Las extensiones de Pandoc, los ajustes de Hugo, los plugins, los filtros y las integraciones de JavaScript determinan cómo se comporta Markdown.

Commitea los archivos de configuración relevantes con la fuente:

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

Una extensión .md por sí sola no captura el entorno de publicación. Para un enfoque estructurado para documentar estas decisiones, consulta Registros de decisiones para el desarrollo impulsado por IA.

Prueba Markdown contra cada objetivo importante

La vista previa visual en un solo editor no es suficiente. El editor puede soportar un dialecto más rico que el renderizador de producción.

Para Pandoc, prueba formatos de entrada explícitos:

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

Las advertencias y la puntuación de fuente visible revelan qué funciones son específicas de un dialecto.

Para Hugo, construye el sitio de producción:

hugo --gc --minify

Luego inspecciona el HTML generado en lugar de depender solo de la vista previa del editor.

Para los repositorios, muestra el archivo commiteado en la plataforma de alojamiento real. Las extensiones de Markdown locales en VS Code pueden no coincidir con GitHub o GitLab.

Solución de problemas para discrepancias comunes de renderizado

Cuando un archivo que funcionaba en una plataforma se rompe en otra, el fallo generalmente cae en una de unas pocas patrones repetibles. La tabla siguiente enumera el síntoma tal como lo verías realmente, la causa más probable y un comando o verificación concreta para confirmarlo y corregirlo.

Este es el primer paso más rápido antes de asumir un “error” de Markdown — la mayoría de estas discrepancias son una extensión faltante o una función exclusiva de la plataforma, no sintaxis rota. Para problemas específicos de cercos de código, como falta de resaltado de sintaxis o identificadores de lenguaje no soportados, consulta la guía dedicada sobre Bloques de código de Markdown.

Linta el subconjunto portable

Un linter de Markdown no puede garantizar la compatibilidad del renderizador, pero puede eliminar la ambigüedad evitable.

Las reglas útiles incluyen:

• Usa estilos de encabezado consistentes
• Añade líneas en blanco alrededor de listas y bloques de código
• Usa código delimitado en lugar de indentado
• Especifica los lenguajes de los cercos de código
• Evita saltar niveles de encabezado
• Usa marcadores de lista consistentes
• Evita el énfasis ambiguo alrededor de la puntuación
• Mantén los saltos de línea consistentes
• Valida enlaces e imágenes

Para la publicación multiobjetivo, añade una prueba de construcción para cada renderizador importante en lugar de depender solo de la linting de sintaxis.

Convirtiendo entre dialectos con Pandoc

Pandoc puede normalizar documentos de un dialecto a otro:

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

O convertir GFM a Pandoc Markdown:

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

Esto es útil, pero la conversión no está garantizada para preservar cada función.

Las posibles pérdidas incluyen:

• Referencias específicas de la plataforma
• Estilizado de avisos
• Tablas complejas
• Objetos de aplicación incrustados
• Atributos personalizados
• Comportamiento de HTML sin procesar
• Sintaxis de plugins
• Renderizado de diagramas
• Espaciado y formato exactos

Pandoc preserva la estructura del documento mejor que el formato de la fuente original. Trata la conversión como un paso de construcción, no como un formateador de texto reversible.

Estrategia recomendada para sitios de Hugo

Para un blog técnico de Hugo, la política más práctica es:

1. Usa CommonMark para el discurso y la estructura centrales.
2. Habilita un pequeño conjunto documentado de extensiones de Goldmark.
3. Usa tablas y listas de tareas de estilo GFM donde mejoren la legibilidad.
4. Implementa Mermaid a través de un render hook o shortcode consistente.
5. Maneja las matemáticas a través de una canalización documentada de KaTeX o MathJax.
6. Usa el front matter de Hugo solo al comienzo de los archivos de contenido.
7. Prefiere los render hooks y los shortcodes sobre el HTML sin procesar.
8. Mantén los enlaces de fuente como enlaces de Markdown estándar cuando sea posible.
9. Prueba los documentos migrados o de origen externo a través de Hugo.
10. Documenta cualquier sintaxis que no se renderice correctamente en GitHub.

Este enfoque acepta que el contenido de Hugo no es universalmente portable a la vez que mantiene la frontera de portabilidad visible.

El peor enfoque es la mezcla accidental de dialectos: avisos de GitHub, incrustaciones de Obsidian, atributos de Pandoc y shortcodes de Hugo colocados en el mismo documento sin un flujo de trabajo de construcción definido.

Tabla de decisiones

Conclusión

CommonMark, GitHub Flavored Markdown y Pandoc Markdown no son versiones competidoras del mismo producto. Resuelven diferentes problemas.

CommonMark proporciona un fundamento de análisis fiable. GFM añade funciones prácticas para la colaboración en software, mientras que Pandoc Markdown convierte Markdown en un lenguaje de fuente rico para la publicación y la conversión.

La regla más segura es simple: escribe el dialecto más pequeño que satisfaga el destino real. Usa CommonMark cuando el contenido debe viajar, GFM cuando la colaboración de estilo GitHub es el objetivo, y Pandoc Markdown cuando la estructura del documento y los formatos de salida importan más que el renderizado universal.

La portabilidad de Markdown no se logra evitando cada extensión. Se logra sabiendo qué extensiones forman parte del contrato de fuente y probándolas en cada renderizador que importe.

Referencias

• Especificación de CommonMark
• Especificación de GitHub Flavored Markdown
• Pandoc Markdown
• Documentación de Goldmark
• Configuración de Goldmark en Hugo
• Escribiendo expresiones matemáticas en GitHub