GFM vs CommonMark vs Pandoc Markdown: comparación de sintaxis

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

El problema es que “Markdown” describe una familia de sintaxis, analizadores (parsers) y características de plataforma relacionadas, en lugar de un único formato de documento universal. CommonMark define un núcleo portable preciso, GitHub Flavored Markdown añade características útiles para la colaboración en software, y Pandoc Markdown expande el lenguaje hacia un formato serio de autoría de documentos.

La elección entre ellos depende de dónde debe renderizarse el documento. Un archivo README, una entrada de blog en Hugo y un artículo académico tienen cada uno requisitos diferentes. Esta comparación es parte del panorama más amplio de las 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 pueda elegir la sintaxis correcta para su entorno objetivo. Para una referencia rápida de sintaxis, la hoja de trucos de Markdown cubre los elementos de formato esenciales.

Markdown no es un solo lenguaje

La sintaxis original de Markdown fue intencionalmente pequeña y especificada de manera laxa. Eso hizo que fuera fácil de leer e implementar, pero diferentes analizadores comenzaron a interpretar entradas ambiguas de manera diferente.

CommonMark se creó para definir reglas de análisis consistentes para las estructuras fundamentales de Markdown. GitHub Flavored Markdown, usualmente llamado GFM, se construye sobre esa base con varias extensiones ampliamente utilizadas.

Pandoc Markdown adopta un enfoque diferente. En lugar de permanecer como una sintaxis web pequeña, añade características de documento 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 cada implementación. Cada renderizador puede habilitar, deshabilitar o añadir sintaxis de forma independiente.

La respuesta corta

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

Utilice GFM al escribir archivos README, solicitudes de extracción (pull requests), plantillas de incidencias y documentación técnica destinada principalmente a plataformas compatibles con GitHub.

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

Para un blog técnico de Hugo, utilice el núcleo de CommonMark más las extensiones de Goldmark que su sitio habilite explícitamente. No asuma que cada característica visible en GitHub funcionará simplemente porque Hugo se describa como compatible con GFM.

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

CommonMark: El núcleo portable

CommonMark es una especificación formal para el lenguaje básico de Markdown. Su principal contribución no es una gran colección de características, 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 vallas (fenced) e indentados
• Énfasis y énfasis fuerte
• Enlaces e imágenes
• Enlaces estilo referencia
• Código en línea
• Separadores temáticos
• Bloques HTML crudos
• Saltos de línea duros y suaves

Un documento CommonMark aún puede comportarse de manera diferente en la capa de presentación. CSS, resaltado de sintaxis, anclas de encabezados, saneamiento HTML y políticas de enlaces están fuera de las reglas de análisis del núcleo.

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

Un ejemplo portable de CommonMark

# Despliegue del Servicio

El servicio expone una API HTTP pequeña.

## Requisitos

- Linux
- Docker
- 8 GB de memoria

## Iniciar el servicio

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

Consulte la [guía de configuración](configuration.md) para obtener detalles.

Este tipo de documento funciona en casi todos los entornos modernos de Markdown. Utiliza encabezados, párrafos, listas, código con vallas y enlaces ordinarios sin depender de extensiones específicas del 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 características comúnmente necesarias en la documentación de repositorios y la colaboración.

La especificación formal de GFM añade:

• Tablas con tuberías (pipe tables)
• Elementos de listas de tareas
• Tachado
• Autovínculos extendidos
• Restricciones alrededor de algunas etiquetas HTML crudas

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

Tablas de 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 opciones de alineación, consulte Tablas en Markdown.

Listas de tareas de GFM

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

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

Tachado de GFM

Utilice el ~~antiguo endpoint~~ nuevo endpoint.

El tachado es ampliamente soportado, pero sigue siendo una extensión en lugar de sintaxis portable de CommonMark.

Autovínculos de GFM

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

Visite https://example.com/docs para obtener detalles.

En CommonMark estricto, los autovínculos explícitos utilizan 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 la suposición de que cada característica de Markdown visible en GitHub pertenece a la especificación GFM.

No es así.

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

• Expresiones matemáticas
• Diagramas Mermaid
• Alertas
• Referencias a incidencias y solicitudes de extracción
• Menciones de usuarios y equipos
• Referencias de commits
• Shortcodes de emojis
• Secciones HTML colapsables
• Previsualizaciones de color
• Enlaces relativos al repositorio
• Anclas de encabezados automáticas

Algunas de estas características son extensiones de sintaxis. Otras son comportamiento de post-procesamiento o integraciones con datos de GitHub.

Esta distinción importa porque otro renderizador puede reclamar acertadamente compatibilidad con GFM sin implementar el renderizador de matemáticas de GitHub, la integración de Mermaid, las referencias de incidencias o el estilo de alertas.

Diagramas Mermaid de GitHub

GitHub renderiza un bloque de código con valla 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 mejorado es específico de la plataforma. Para una introducción práctica a la sintaxis de Mermaid, consulte el Inicio rápido de Diagramas Mermaid.

Expresiones matemáticas de GitHub

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

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

$$
C = 2nlhd
$$

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

Alertas de GitHub

GitHub soporta citas en bloque estilo alerta como:

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

En GitHub, esto puede aparecer como una advertencia estilizada. En un renderizador CommonMark plano, usualmente aparece como una cita en bloque ordinaria que contiene [!WARNING].

Ese comportamiento de respaldo es legible, lo que hace que las alertas de GitHub sean menos peligrosas que las extensiones que desaparecen por completo. Aún así, no son elementos de presentación portables.

Pandoc Markdown: Markdown como lenguaje de documento

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

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

• Bloques de metadatos YAML
• Notas al pie
• Citas
• Múltiples formatos de tabla
• Listas de definición
• Notación matemática
• Identificadores y atributos de encabezados
• Atributos de bloques de código
• Divisiones con vallas
• Span bracketed
• Superíndice y subíndice
• Tachado
• Bloques de línea
• Listas de ejemplo numeradas
• LaTeX crudo
• HTML crudo
• 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 de Pandoc

Markdown tiene varios dialectos incompatibles.[^dialects]

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

La sintaxis de notas al pie es soportada por muchas herramientas modernas, pero no es parte de CommonMark ni del GFM formal.

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

Citas de Pandoc

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

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

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

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

Listas de definición de Pandoc

CommonMark
: Una especificación precisa para el núcleo de Markdown.

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

Pandoc Markdown
: Un formato de autoría extendido para conversión de documentos.

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

Atributos de encabezados de Pandoc

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

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

Este es uno de los ejemplos más claros de sintaxis útil que no debería colocarse en un documento esperado para renderizarse en todas partes.

Divisiones con vallas de 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 valla. 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 característica añadida por GitHub.com, Hugo, Obsidian, GitLab u otra plataforma.

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

¿Qué sintaxis funciona en GitHub?

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

Generalmente puede usar:

• Sintaxis CommonMark
• Tablas
• Listas de tareas
• Tachado
• Autovínculos extendidos
• Vallas de código con resaltado de sintaxis
• Referencias específicas de GitHub
• Matemáticas soportadas por GitHub
• Diagramas soportados por GitHub
• Alertas de GitHub
• Notas al pie donde son soportadas por la superficie de contenido

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

Para archivos de repositorio que también se publican en otro lugar, pruebe el fuente en el segundo renderizador en lugar de tratar la previsualización de GitHub como autoritativa.

¿Qué sintaxis funciona en Hugo?

Hugo utiliza Goldmark como su renderizador de Markdown por defecto. Goldmark se conforma 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 con vallas
• Tablas con tuberías
• Tachado
• Listas de tareas
• IDs de encabezados automáticos
• Resaltado de sintaxis
• Notas al pie cuando la extensión está habilitada
• Listas de definición cuando están habilitadas
• Sustituciones tipográficas cuando están habilitadas

Hugo también añade características 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 características de Hugo no viajan con el archivo Markdown. Para un ejemplo práctico de despliegue de Hugo, consulte Desplegar Hugo en AWS S3.

El front matter de Hugo no es contenido 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 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, por lo tanto, ser reconocida en más de una herramienta sin tener el mismo significado semántico.

HTML crudo en Hugo

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

Un bloque como:

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

puede ser omitido a menos que el renderizado de HTML crudo esté habilitado o el contenido se implemente a través de un shortcode o render hook.

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

Mermaid en Hugo

Un bloque con valla mermaid sigue siendo solo un bloque de código a menos que el tema de Hugo, el render hook, el shortcode o la tubería de JavaScript lo transformen en un diagrama.

GitHub y Hugo pueden, por lo tanto, aceptar fuente Mermaid idéntica mientras utilizan 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 características de portabilidad más útiles de Pandoc. El operador puede decirle a Pandoc qué dialecto afirma usar el fuente en lugar de depender de una extensión de archivo .md vaga.

Pandoc también le 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 característica:

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

Puede inspeccionar las extensiones disponibles con:

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

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

¿Qué sintaxis funciona en Obsidian?

Obsidian almacena notas como archivos Markdown, pero su modelo de autoría incluye varias características específicas de la aplicación.

Ejemplos comunes incluyen:

• Enlaces Wiki
• Notas incrustadas
• Archivos incrustados
• Alertas (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]]

tiene significado dentro de un vault de Obsidian. GitHub, CommonMark y un lector de Pandoc por defecto normalmente lo muestran como texto entre corchetes literales.

Un incrustado es aún más específico de la aplicación:

![[tabla-de-compatibilidad]]

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

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, consulte Obsidian para la Gestión del Conocimiento Personal.

¿Qué sintaxis funciona en GitLab?

GitLab Flavored Markdown utiliza CommonMark como su núcleo e incluye características 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 características de colaboración.

Un README escrito en GFM conservado usualmente se mueve entre GitHub y GitLab sin daños mayores.

Las integraciones de plataforma no viajan tan fiablemente. Las referencias de incidencias, menciones de usuarios, diagramas, manejo de matemáticas y 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í” aún no garantiza HTML idéntico o presentación visual. Significa que el entorno reconoce la característica general.

Sintaxis que usualmente es segura en todas partes

El subconjunto portable más seguro incluye:

• Encabezados ATX usando #
• Párrafos ordinarios
• Líneas en blanco entre bloques
• - para listas desordenadas
• 1. para listas ordenadas
• Bloques de código con vallas usando comillas invertidas
• Código en línea usando comillas invertidas
• Énfasis usando *texto*
• Énfasis fuerte usando **texto**
• Enlaces ordinarios
• Imágenes ordinarias
• Citas en bloque
• Separadores temáticos
• Autovínculos 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
- Un GPU soportado

## Configuración

Cree un archivo llamado `compose.yaml`.

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

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

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

Esta sintaxis viaja bien porque no depende de tablas, notas al pie, atributos, callouts 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 características.

Tablas con tuberías

Las tablas con tuberías son 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, considere listas cortas o HTML semántico generado durante un paso de compilació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 el fuente literalmente

Use notas al pie cuando la tubería de publicación sea conocida. Evite depender de ellas en archivos README que deben renderizarse a través de sistemas arbitrarios.

IDs de encabezados y atributos

Esta sintaxis de Pandoc no es portable:

## Instalación {#instalacion .procedimiento}

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

También evite codificar enlaces a IDs de encabezados auto-generados a menos que cada objetivo utilice las mismas reglas de slugificación.

Callouts y alertas

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

Un respaldo portable es una cita en bloque ordinaria:

> Advertencia: Haga 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 encabezados y el comportamiento de resolución pertenecen a la aplicación.

Use enlaces Markdown estándar en contenido destinado para publicación:

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

HTML crudo

El HTML crudo es la salida de emergencia usual 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
• Saneiar elementos seleccionados
• Permitir bloques pero no elementos en línea
• Rechazar el análisis de Markdown dentro de HTML
• Pasarlo sin cambios solo en modo confiable

Use HTML crudo solo cuando el objetivo de publicación esté controlado.

Notación matemática

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

El 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 de matemáticas diferente

Elija una tubería de matemáticas y pruébela en cada entorno objetivo.

Mermaid y otros bloques de diagramas

Una valla de código Mermaid es sintácticamente segura porque los renderizadores no soportados normalmente la muestran como código.

El resultado semántico aún es diferente. Los lectores pueden ver un diagrama de arquitectura renderizado en GitHub y fuente Mermaid cruda en otro entorno.

Esto 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 con vallas.

Capa 2: Compatibilidad de transformación

¿La plataforma aplica procesamiento adicional?

Los ejemplos incluyen:

• Renderizar Mermaid
• Resolver citas
• Expandir enlaces wiki
• Enlazar números de incidencias
• Procesar shortcodes
• Generar una tabla de contenidos

Capa 3: Compatibilidad de presentación

¿El resultado se ve y comporta apropiadamente?

Los ejemplos incluyen:

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

Dos plataformas pueden analizar sintaxis idéntica mientras producen presentación sustancialmente diferente.

Un mejor modelo de portabilidad

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

1. ¿En qué dialecto está escrito el 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”.

Elija un dialecto por caso de uso

Archivos README

Use GFM.

Los archivos README se benefician de:

• Tablas
• Listas de tareas
• Código con vallas
• Autovínculos
• Tachado
• Referencias de GitHub

Evite la dependencia excesiva de características exclusivas de GitHub cuando el repositorio se refleje en GitLab, se renderice en un registro de paquetes o se incluya en documentación generada.

Artículos técnicos de Hugo

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

Las tablas, vallas de código, notas al pie y Mermaid pueden ser razonables porque usted controla la tubería de compilación. Prefiera shortcodes de Hugo o render hooks sobre incrustar grandes cantidades de HTML crudo.

Mantenga la sintaxis específica de Hugo aislada y fácil de encontrar.

Documentos académicos

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

Almacene el comando de Pandoc, el archivo de valores predeterminados, los filtros, la bibliografía y las plantillas junto al fuente. El archivo fuente solo no describe completamente la compilación.

Libros y documentación de formato largo

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

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

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

Notas y bases de conocimiento personal

Use la sintaxis nativa de la aplicación de notas seleccionada cuando las características de la aplicación proporcionen valor real.

Los enlaces wiki, incrustados y callouts de Obsidian son útiles dentro de un vault. Trate la exportación como un proceso de compilación en lugar de asumir que los archivos crudos ya son publicaciones portables.

Documentación compartida a través de sistemas desconocidos

Use un subconjunto CommonMark conservador.

Evite:

• Enlaces Wiki
• Alertas de plataforma
• Atributos de encabezados
• Citas
• HTML crudo
• Contenedores personalizados
• Incrustados de aplicación
• Shortcodes

La portabilidad usualmente requiere renunciar a características de conveniencia.

Reglas prácticas para Markdown portable

Comience con la estructura CommonMark

Use 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ñada características GFM deliberadamente

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

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

Aíslar extensiones de plataforma

Mantenga la sintaxis específica de la plataforma en bloques claramente identificables.

Por ejemplo, centralice shortcodes de Hugo, citas de Pandoc o incrustados de Obsidian en lugar de dispersarlos a través de cada párrafo.

El aislamiento hace que la conversión posterior sea más fácil.

Prefiera la degradación elegante

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

Un incrustado wiki puede degradarse en un nombre de archivo sin explicar, mientras que una división con valla de Pandoc puede exponer puntuación alrededor del contenido.

Elija extensiones cuyo respaldo permanezca comprensible.

No dependa de IDs de encabezados auto-generados

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

Para enlaces entre documentos, use IDs explícitos soportados por el renderizador solo cuando la tubería objetivo esté controlada. De lo contrario, enlace al documento en lugar de a un fragmento generado.

Mantenga la configuración de compilación con el contenido

Las extensiones de Pandoc, configuraciones de Hugo, plugins, filtros e integraciones de JavaScript determinan cómo se comporta Markdown.

Commitee archivos de configuración relevantes con el fuente:

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

Una extensión .md sola no captura el entorno de publicación. Para un enfoque estructurado para documentar estas decisiones, consulte Registros de Decisión para Desarrollo Impulsado por IA.

Pruebe Markdown contra cada objetivo importante

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

Para Pandoc, pruebe 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é características son específicas del dialecto.

Para Hugo, compile el sitio de producción:

hugo --gc --minify

Luego inspeccione el HTML generado en lugar de depender solo de una previsualización del editor.

Para repositorios, vea 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 de discrepancias de renderizado comunes

Cuando un archivo que funcionó en una plataforma se rompe en otra, el fallo usualmente cae en uno de un puñado de patrones repetibles. La tabla a continuación lista el síntoma como lo vería realmente, la causa más probable y un comando o verificación concreta para confirmar y arreglarlo.

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 característica exclusiva de la plataforma, no sintaxis rota. Para problemas específicos de vallas de código como resaltado de sintaxis faltante o identificadores de lenguaje no soportados, consulte la guía dedicada sobre bloques de código Markdown.

Lint el subconjunto portable

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

Las reglas útiles incluyen:

• Usar estilos de encabezados consistentes
• Añadir líneas en blanco alrededor de listas y bloques de código
• Usar vallas en lugar de código indentado
• Especificar lenguajes de vallas de código
• Evitar niveles de encabezados saltados
• Usar marcadores de lista consistentes
• Evitar énfasis ambiguo alrededor de puntuación
• Mantener finales de línea consistentes
• Validar enlaces e imágenes

Para publicación multi-objetivo, añada una prueba de compilación para cada renderizador importante en lugar de depender solo de linting de sintaxis.

Convertir 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 característica.

Las pérdidas potenciales incluyen:

• Referencias específicas de plataforma
• Estilo de callouts
• Tablas complejas
• Objetos de aplicación incrustados
• Atributos personalizados
• Comportamiento de HTML crudo
• Sintaxis de plugin
• Renderizado de diagramas
• Espaciado en blanco y formato exacto

Pandoc preserva la estructura del documento mejor que el formato de fuente original. Trate la conversión como un paso de compilació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. Usar CommonMark para prosa y estructura central.
2. Habilitar un pequeño conjunto documentado de extensiones Goldmark.
3. Usar tablas y listas de tareas estilo GFM donde mejoren la legibilidad.
4. Implementar Mermaid a través de un render hook o shortcode consistente.
5. Manejar matemáticas a través de una tubería documentada de KaTeX o MathJax.
6. Usar front matter de Hugo solo al comienzo de archivos de contenido.
7. Preferir render hooks y shortcodes sobre HTML crudo.
8. Mantener enlaces fuente como enlaces Markdown estándar donde sea posible.
9. Probar documentos migrados o de origen externo a través de Hugo.
10. Documentar cualquier sintaxis que no se renderice correctamente en GitHub.

Este enfoque acepta que el contenido de Hugo no es universalmente portable mientras mantiene el límite de portabilidad visible.

El peor enfoque es la mezcla accidental de dialectos: alertas de GitHub, incrustados de Obsidian, atributos de Pandoc y shortcodes de Hugo colocados en el mismo documento sin una tubería de compilación definida.

Tabla de decisión

Conclusión

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

CommonMark proporciona una base de análisis confiable. GFM añade características prácticas para la colaboración en software, mientras que Pandoc Markdown convierte Markdown en un lenguaje fuente rico para publicación y conversión.

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

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

Referencias

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