GFM vs CommonMark vs Pandoc Markdown: Comparação da Sintaxe

Markdown parece uma única língua até que o mesmo arquivo seja renderizado de forma diferente no GitHub, Hugo, Obsidian ou Pandoc. E o problema não é que o Markdown seja pouco confiável.

O problema é que “Markdown” descreve uma família de sintaxes, analisadores e funcionalidades de plataforma relacionados, em vez de um único formato universal de documento. O CommonMark define um núcleo portátil preciso, o GitHub Flavored Markdown adiciona funcionalidades úteis para a colaboração em software, e o Pandoc Markdown expande a língua para um formato sério de criação de documentos.

A escolha entre eles depende de onde o documento deve ser renderizado. Um arquivo README, uma publicação de blog no Hugo e um artigo acadêmico têm cada um requisitos diferentes. Esta comparação faz parte do panorama mais amplo das ferramentas de documentação e cobre os dialetos formais, extensões específicas de plataforma e regras práticas de portabilidade, para que você possa escolher a sintaxe certa para o seu ambiente de destino. Para uma referência rápida de sintaxe, a folha de dicas de Markdown cobre os elementos essenciais de formatação.

O Markdown Não É Uma Única Língua

A sintaxe original do Markdown foi intencionalmente pequena e especificada de forma frouxa. Isso a tornou fácil de ler e implementar, mas diferentes analisadores começaram a interpretar entradas ambíguas de maneira diferente.

O CommonMark foi criado para definir regras de análise consistentes para as estruturas fundamentais do Markdown. O GitHub Flavored Markdown, geralmente chamado de GFM, constrói sobre essa fundação com várias extensões amplamente utilizadas.

O Pandoc Markdown adota uma abordagem diferente. Em vez de permanecer uma sintaxe pequena voltada para a web, ele adiciona recursos de documento como citações, metadados, notas de rodapé, listas de definições, atributos e notação matemática.

Um relacionamento simplificado parece-se com isto:

Esta hierarquia é útil, mas não é herança exata em cada implementação. Cada renderizador pode ativar, desativar ou adicionar sintaxe independentemente.

A Resposta Curta

Use sintaxe compatível com CommonMark quando a portabilidade for o mais importante.

Use GFM ao escrever arquivos README, solicitações de merge (pull requests), modelos de problema (issue templates) e documentação técnica destinada principalmente a plataformas compatíveis com o GitHub.

Use Pandoc Markdown quando o documento de origem deve se tornar PDF, DOCX, EPUB, LaTeX, slides ou um artigo acadêmico com citações e metadados.

Para um blog técnico no Hugo, use o núcleo CommonMark mais as extensões Goldmark que seu site explicitamente ativa. Não assuma que cada recurso visível no GitHub funcionará apenas porque o Hugo é descrito como compatível com GFM.

Opinião fundamentada: se você lembrar apenas de uma regra para um blog técnico no Hugo, trate o CommonMark mais tabelas e listas de tarefas estilo GFM como padrão, e trate tudo o mais — notas de rodapé, matemática, avisos, atributos de cabeçalho — como uma extensão explícita e testada, em vez de um padrão assumido. Esse único hábito previne a maioria dos falhas de portabilidade descritas abaixo.

CommonMark: O Núcleo Portátil

O CommonMark é uma especificação formal para a língua básica de Markdown. Sua principal contribuição não é uma grande coleção de recursos, mas a análise consistente.

Ele define como os analisadores devem interpretar:

• Parágrafos
• Cabeçalhos ATX e Setext
• Citações em bloco
• Listas ordenadas e não ordenadas
• Blocos de código com cercas e com indentação
• Ênfase e ênfase forte
• Links e imagens
• Links em estilo de referência
• Código inline
• Quebras temáticas
• Blocos HTML em bruto
• Quebras de linha duras e suaves

Um documento CommonMark ainda pode se comportar de maneira diferente na camada de apresentação. CSS, realce de sintaxe, âncoras de cabeçalho, saneamento de HTML e políticas de links estão fora das regras de análise do núcleo.

Portanto, o CommonMark deve ser tratado como uma linha de base estrutural confiável, não como uma promessa de que cada renderizador produzirá uma página idêntica.

Um Exemplo Portátil de CommonMark

# Deploy de Serviço

O serviço expõe uma pequena API HTTP.

## Requisitos

- Linux
- Docker
- 8 GB de memória

## Iniciar o serviço

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

Veja o [guia de configuração](configuration.md) para detalhes.

Este tipo de documento funciona em quase todos os ambientes modernos de Markdown. Ele usa cabeçalhos, parágrafos, listas, código com cercas e links comuns, sem depender de extensões específicas de dialeto.

GitHub Flavored Markdown: CommonMark para Projetos de Software

O GitHub Flavored Markdown é um dialeto formal baseado no CommonMark. Ele preserva o modelo de análise do CommonMark e adiciona recursos comumente necessários em documentação de repositórios e colaboração.

A especificação formal do GFM adiciona:

• Tabelas com barras verticais (pipe tables)
• Itens de lista de tarefas
• Tachado (Strikethrough)
• Autolinks estendidos
• Restrições em torno de algumas tags HTML em bruto

Essas extensões agora são tão comuns que muitos usuários acham que fazem parte do Markdown padrão. Elas não fazem parte do núcleo CommonMark.

Tabelas no GFM

| Backend | Melhor uso |
|---|---|
| Ollama | Experimentos locais |
| vLLM | Inferência compartilhada |
| SGLang | Cargas de trabalho estruturadas |

Um analisador CommonMark estrito é permitido para tratar isso como texto de parágrafo comum. Um analisador compatível com GFM o reconhece como uma tabela. Para uma visão mais aprofundada da sintaxe de tabelas e opções de alinhamento, veja Tabelas no Markdown.

Listas de Tarefas no GFM

- [x] Instalar Docker
- [x] Baixar o modelo
- [ ] Adicionar monitoramento

A sintaxe de lista de tarefas é útil em problemas, solicitações de merge e documentação de projeto. Fora de um renderizador que a suporte, ela pode aparecer como uma lista comum contendo colchetes literais.

Tachado no GFM

Use o ~~antigo endpoint~~ novo endpoint.

O tachado é amplamente suportado, mas ainda é uma extensão, em vez de sintaxe CommonMark portátil.

Autolinks no GFM

O GFM reconhece mais texto parecido com URL e e-mail sem exigir colchetes angulares ou sintaxe explícita de link.

Visite https://example.com/docs para detalhes.

No CommonMark estrito, os autolinks explícitos usam colchetes angulares:

<https://example.com/docs>

A forma explícita é mais segura quando um documento deve passar por processadores de Markdown desconhecidos.

O GitHub.com Suporta Mais Do Que o GFM Formal

Uma fonte frequente de confusão é a suposição de que cada recurso de Markdown visível no GitHub pertence à especificação do GFM.

Ele não pertence.

O GitHub.com adiciona processamento e funcionalidades em nível de plataforma ao redor do analisador GFM. Dependendo do contexto, o GitHub pode suportar:

• Expressões matemáticas
• Diagramas Mermaid
• Alertas
• Referências a problemas e solicitações de merge
• Menções de usuários e equipes
• Referências a commits
• Shortcodes de emoji
• Seções HTML recolhíveis
• Pré-visualizações de cor
• Links relativos ao repositório
• Âncoras de cabeçalho automáticas

Alguns desses recursos são extensões de sintaxe. Outros são comportamento de pós-processamento ou integrações com dados do GitHub.

Essa distinção importa porque outro renderizador pode afirmar compatibilidade com GFM com precisão sem implementar o renderizador de matemática, integração Mermaid, referências de problema ou estilo de alerta do GitHub.

Diagramas Mermaid no GitHub

O GitHub renderiza um bloco de código cercado marcado como mermaid como um diagrama:

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

Um renderizador GFM genérico pode exibir o mesmo bloco como código fonte realçado. O Markdown permanece válido, mas a renderização aprimorada é específica da plataforma. Para uma introdução prática à sintaxe do Mermaid, veja o Início Rápido em Diagramas Mermaid.

Expressões Matemáticas no GitHub

O GitHub suporta expressões matemáticas inline e em bloco usando delimitadores de dólar e formas adicionais de escape.

O tamanho do cache é aproximadamente $2nlhd$ bytes.

$$
C = 2nlhd
$$

Matemática não faz parte do GFM formal. Mover este conteúdo para outro renderizador requer uma extensão de matemática compatível, como KaTeX, MathJax ou suporte de matemática do Pandoc.

Alertas do GitHub

O GitHub suporta citações em bloco estilo alerta, como:

> [!WARNING]
> Alterar esta configuração limpa o cache.

No GitHub, isso pode aparecer como um aviso estilizado. Em um renderizador CommonMark simples, geralmente aparece como uma citação em bloco comum contendo [!WARNING].

Esse fallback é legível, o que torna os alertas do GitHub menos perigosos do que extensões que desaparecem completamente. Eles ainda não são elementos de apresentação portáveis.

Pandoc Markdown: Markdown Como Língua de Documento

O Pandoc Markdown é projetado para conversão de documentos, em vez de para um único site. Ele usa o Markdown como a sintaxe de origem para produzir HTML, PDF, DOCX, EPUB, LaTeX, apresentações e outros formatos.

Seu leitor padrão de Markdown inclui um grande conjunto de extensões. As capacidades importantes incluem:

• Blocos de metadados YAML
• Notas de rodapé
• Citações
• Múltiplos formatos de tabela
• Listas de definições
• Notação matemática
• Identificadores e atributos de cabeçalho
• Atributos de bloco de código
• Divisões com cercas
• Span com colchetes
• Superíndice e subíndice
• Tachado
• Blocos de linha
• Listas de exemplos numerados
• LaTeX em bruto
• HTML em bruto
• Numeração automática de seções
• Processamento de bibliografia

O Pandoc Markdown é muito mais expressivo que o CommonMark ou o GFM formal. Essa expressividade o torna poderoso para publicação, mas menos seguro como formato de intercâmbio.

Notas de Rodapé no Pandoc

O Markdown tem vários dialetos incompatíveis.[^dialects]

[^dialects]: CommonMark, GFM e Pandoc Markdown são três
    exemplos importantes.

A sintaxe de notas de rodapé é suportada por muitas ferramentas modernas, mas não faz parte do CommonMark ou do GFM formal.

O GitHub atualmente renderiza notas de rodapé em vários contextos de conteúdo, mas isso é um recurso da plataforma do GitHub, em vez de uma garantia formal do GFM. Um renderizador que afirma apenas compatibilidade com CommonMark ou GFM pode não suportá-los.

Citações no Pandoc

PagedAttention melhora o gerenciamento de memória do cache KV
[@kwon2023pagedattention].

Com um arquivo de bibliografia e estilo de citação, o Pandoc pode resolver isso em uma citação acadêmica formatada e uma bibliografia.

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

A sintaxe de citação permanece legível em um renderizador não suportado, mas não se tornará uma referência formatada sem o Pandoc ou outro processador de citações compatível. A flexibilidade do lado do leitor do Pandoc também sustenta fluxos de conversão na direção oposta — veja convertendo documentos Word para Markdown para um exemplo prático de usar o dialeto estendido do Pandoc como formato intermediário.

Listas de Definição no Pandoc

CommonMark
: Uma especificação precisa para o núcleo do Markdown.

GFM
: Um dialeto baseado em CommonMark com extensões orientadas a software.

Pandoc Markdown
: Um formato de criação estendido para conversão de documentos.

Listas de definição são úteis em manuais, glossários e livros técnicos. Elas geralmente degradam mal em renderizadores que não as suportam, porque as linhas com dois-pontos permanecem visíveis como texto simples.

Atributos de Cabeçalho no Pandoc

## Configuração de Cache {#cache-config .deployment}

O Pandoc interpreta as chaves como uma lista explícita de identificador e classe. Muitos outros renderizadores de Markdown mostram o texto do atributo diretamente no cabeçalho.

Este é um dos exemplos mais claros de sintaxe útil que não deve ser colocado em um documento esperado para ser renderizado em qualquer lugar.

Divisões com Cercas no Pandoc

::: warning
Alterar esta opção reinicia o servidor.

O Pandoc converte isso em uma divisão estrutural com uma classe. Modelos, CSS, filtros ou escritores de saída podem decidir como essa estrutura deve aparecer.

A maioria dos renderizadores CommonMark e GFM não reconhece a cerca. Eles exibem os dois-pontos e o conteúdo como texto comum.

CommonMark vs GFM vs Pandoc Markdown

A matriz a seguir descreve os dialetos formais, não cada recurso adicionado pelo GitHub.com, Hugo, Obsidian, GitLab ou outra plataforma.

A palavra “Não” não significa que uma plataforma nunca pode suportar o recurso. Significa que o recurso não é garantido pela especificação formal daquele dialeto.

Qual Sintaxe Funciona no GitHub?

Para arquivos README, problemas, solicitações de merge, discussões e wikis, o GFM é a linha de base natural.

Você geralmente pode usar:

• Sintaxe CommonMark
• Tabelas
• Listas de tarefas
• Tachado
• Autolinks estendidos
• Cercas de código com realce de sintaxe
• Referências específicas do GitHub
• Matemática suportada pelo GitHub
• Diagramas suportados pelo GitHub
• Alertas do GitHub
• Notas de rodapé onde suportadas pela superfície de conteúdo

O risco de portabilidade começa quando o GitHub realiza renderização adicional além do GFM formal. Diagramas Mermaid, notação matemática, referências de problemas e apresentação de alertas podem não sobreviver fora do GitHub.

Para arquivos de repositório que também são publicados em outros lugares, teste a fonte no segundo renderizador, em vez de tratar a pré-visualização do GitHub como autoritativa.

Qual Sintaxe Funciona no Hugo?

O Hugo usa o Goldmark como seu renderizador padrão de Markdown. O Goldmark conforma-se ao CommonMark e fornece extensões compatíveis com partes importantes do GFM.

Em uma configuração típica do Hugo, os seguintes funcionam bem:

• Estrutura CommonMark
• Blocos de código com cercas
• Tabelas com barras verticais
• Tachado
• Listas de tarefas
• IDs de cabeçalho automáticos
• Realce de sintaxe
• Notas de rodapé quando a extensão é ativada
• Listas de definições quando ativadas
• Substituições tipográficas quando ativadas

O Hugo também adiciona recursos fora do Markdown através de:

• Metadados de front matter
• Shortcodes
• Ganchos de renderização (Render hooks)
• Recursos de página
• Funções de referência interna
• Processamento de modelos
• Configuração do site

Esses recursos do Hugo não viajam com o arquivo de Markdown. Para um exemplo prático de implantação do Hugo, veja Implantar Hugo no AWS S3.

Front Matter do Hugo Não É Conteúdo de Markdown

Uma página do Hugo comumente começa com metadados YAML, TOML ou JSON:

---
title: "Compatibilidade de Markdown"
description: "Comparar dialetos e renderizadores de Markdown."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

O Pandoc também pode reconhecer blocos de metadados YAML, mas interpreta os campos de acordo com seus próprios modelos e escritores. O GitHub normalmente exibe o bloco como uma seção parecida com YAML ou o trata como metadados de repositório apenas em sistemas específicos.

Portanto, a mesma sintaxe pode ser reconhecida em mais de uma ferramenta sem ter as mesmas semânticas.

HTML em Bruto no Hugo

O Goldmark não renderiza HTML em bruto potencialmente inseguro por padrão em uma configuração padrão do Hugo.

Um bloco como:

<div class="notice">
  Reinicie o serviço após alterar este valor.
</div>

pode ser omitido, a menos que a renderização de HTML em bruto seja ativada ou o conteúdo seja implementado através de um shortcode ou gancho de renderização.

Para um blog técnico controlado, ativar HTML em bruto pode ser razoável. Ainda assim, isso torna a fonte menos portátil e deve ser uma decisão deliberada em nível de site.

Mermaid no Hugo

Um bloco cercado mermaid ainda é apenas um bloco de código, a menos que o tema do Hugo, gancho de renderização, shortcode ou pipeline de JavaScript o transforme em um diagrama.

O GitHub e o Hugo podem, portanto, aceitar fonte Mermaid idêntica enquanto usam mecanismos de renderização completamente diferentes.

Qual Sintaxe Funciona no Pandoc?

O Pandoc pode ler vários dialetos de Markdown explicitamente:

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

Este é um dos recursos de portabilidade mais úteis do Pandoc. O operador pode dizer ao Pandoc qual dialeto a fonte alega usar, em vez de depender de uma extensão de arquivo .md vaga.

O Pandoc também permite que você ative ou desative extensões individuais:

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

Ou começar de um formato mais estreito e adicionar um recurso:

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

Você pode inspecionar extensões disponíveis com:

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

Este modelo de extensão é poderoso, mas significa que “Pandoc Markdown” nem sempre é uma configuração fixa. Comandos de compilação e arquivos de padrão são parte da especificação do documento.

Qual Sintaxe Funciona no Obsidian?

O Obsidian armazena notas como arquivos de Markdown, mas seu modelo de criação inclui vários recursos específicos da aplicação.

Exemplos comuns incluem:

• Links wiki
• Notas incorporadas
• Arquivos incorporados
• Chamadas (Callouts)
• Referências de bloco
• Tags
• Propriedades
• Destaque
• Comentários
• Consultas Dataview de plugins
• Links URI específicos da aplicação

Um link wiki como:

[[Compatibilidade de Markdown]]

é significativo dentro de um cofre (vault) do Obsidian. O GitHub, o CommonMark e um leitor padrão do Pandoc normalmente o exibem como texto colchetado literal.

Um incorporado (embed) é ainda mais específico da aplicação:

![[tabela-compatibilidade]]

O conteúdo referenciado não está presente no próprio arquivo. Exportar ou publicar a nota requer, portanto, uma etapa de expansão que resolve o incorporado.

O Obsidian é um bom exemplo de por que o armazenamento em arquivos .md não garante portabilidade de Markdown. Para uma visão prática do Obsidian como ferramenta de gestão de conhecimento, veja Obsidian para Gestão de Conhecimento Pessoal.

Qual Sintaxe Funciona no GitLab?

O GitLab Flavored Markdown usa o CommonMark como seu núcleo e inclui recursos GFM, como tabelas e listas de tarefas. Ele então adiciona comportamento específico do GitLab, incluindo cruzamentos de referência, notação matemática, diagramas e outros recursos de colaboração.

Um README escrito em GFM conservador geralmente se move entre GitHub e GitLab sem dano maior.

As integrações de plataforma não viajam com tanta confiabilidade. Referências de problemas, menções de usuários, diagramas, processamento de matemática e sintaxe especial de bloco podem se comportar de maneira diferente, mesmo quando o Markdown básico permanece legível.

Matriz de Suporte de Plataforma

Esta matriz descreve o comportamento padrão comum. Temas, plugins, extensões e configuração podem alterar células individuais.

“Sim” ainda não garante HTML ou apresentação visual idênticos. Significa que o ambiente reconhece o recurso geral.

Sintaxe Que Geralmente É Segura em Todos os Lugares

O subconjunto portátil mais seguro inclui:

• Cabeçalhos ATX usando #
• Parágrafos comuns
• Linhas em branco entre blocos
• - para listas não ordenadas
• 1. para listas ordenadas
• Blocos de código com cercas usando crases
• Código inline usando crases
• Ênfase usando *texto*
• Ênfase forte usando **texto**
• Links comuns
• Imagens comuns
• Citações em bloco
• Quebras temáticas
• Autolinks explícitos com colchetes angulares

Um documento intencionalmente conservador pode parecer-se com isto:

# Guia de Implantação

Este guia explica como implantar o serviço.

## Requisitos

- Docker
- Linux
- Um GPU suportado

## Configuração

Crie um arquivo chamado `compose.yaml`.

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

Para mais informações, veja a [referência de configuração](config.md).

> Faça backup dos dados existentes antes de atualizar.

Esta sintaxe viaja bem porque não depende de tabelas, notas de rodapé, atributos, chamadas ou processamento de plataforma.

Sintaxe Que Comumente Quebra

Os problemas de portabilidade tendem a se agrupar em torno de um pequeno número de recursos.

Tabelas com Barras Verticais

Tabelas com barras verticais são bem suportadas por ferramentas orientadas a GFM, mas não por CommonMark estrito.

Uma tabela pode degradar em texto ilegível quando passada por um analisador que não a reconhece. Para documentos altamente portáveis, considere listas curtas ou HTML semântico gerado durante uma etapa de compilação.

Notas de Rodapé

A sintaxe de notas de rodapé se tornou comum, mas permanece uma extensão.

Ferramentas diferentes podem:

• Suportar apenas um formato de nota de rodapé
• Colocar notas de rodapé de maneira diferente
• Gerar identificadores diferentes
• Rejeitar notas de rodapé com múltiplos parágrafos
• Renderizar a fonte literalmente

Use notas de rodapé quando o pipeline de publicação for conhecido. Evite depender delas em arquivos README que devem ser renderizados em sistemas arbitrários.

IDs de Cabeçalho e Atributos

Esta sintaxe do Pandoc não é portátil:

## Instalação {#installation .procedure}

Use um cabeçalho comum e deixe que o renderizador gere sua própria âncora quando a portabilidade for importante.

Evite também codificar fixamente links para IDs de cabeçalho gerados automaticamente, a menos que todos os destinos usem as mesmas regras de slugificação.

Chamadas e Alertas

GitHub, Obsidian, GitLab, MkDocs, Docusaurus e temas do Hugo podem todos suportar blocos parecidos com chamadas, mas eles frequentemente usam sintaxe diferente.

Um fallback portátil é uma citação em bloco comum:

> Aviso: Faça backup do banco de dados antes de atualizar.

É menos impressionante visualmente, mas preserva o significado em todos os lugares.

Links Wiki

Links wiki são concisos dentro de ferramentas de gestão de conhecimento:

[[Cache KV]]

Eles são uma sintaxe ruim para intercâmbio porque o caminho do destino, nome do arquivo, regras de cabeçalho e comportamento de resolução pertencem à aplicação.

Use links de Markdown padrão em conteúdo destinado à publicação:

[Cache KV](kv-cache.md)

HTML em Bruto

HTML em bruto é a saída usual quando o Markdown não pode expressar um layout. É também uma falha comum de portabilidade e segurança.

Um renderizador pode:

• Remover o HTML
• Escapar
• Sanear elementos selecionados
• Permitir blocos, mas não elementos inline
• Recusar a análise de Markdown dentro de HTML
• Passá-lo inalterado apenas em modo confiável

Use HTML em bruto apenas quando o destino de publicação for controlado.

Notação Matemática

Matemática delimitada por dólar é popular, mas não é universalmente interpretada.

A fonte:

A complexidade é $O(n^2)$.

pode se tornar:

• Matemática renderizada
• Texto comum com sinais de dólar
• Ênfase incorreta
• Entrada para um analisador de matemática diferente

Escolha um pipeline de matemática único e teste-o em cada ambiente de destino.

Blocos de Diagrama Mermaid e Outros

Uma cerca de código Mermaid é sintaticamente segura porque renderizadores não suportados geralmente a exibem como código.

O resultado semântico ainda é diferente. Os leitores podem ver um diagrama de arquitetura renderizado no GitHub e fonte Mermaid bruta em outro ambiente.

Isso é degradação graciosa, não compatibilidade verdadeira.

As Três Camadas de Compatibilidade de Markdown

Ajuda separar a compatibilidade em três camadas.

Camada 1: Compatibilidade de Análise

O analisador reconhece a estrutura?

Exemplos incluem cabeçalhos, tabelas, notas de rodapé e divisões com cercas.

Camada 2: Compatibilidade de Transformação

A plataforma aplica processamento adicional?

Exemplos incluem:

• Renderizar Mermaid
• Resolver citações
• Expandir links wiki
• Vincular números de problema
• Processar shortcodes
• Gerar uma tabela de conteúdo

Camada 3: Compatibilidade de Apresentação

O resultado parece e se comporta apropriadamente?

Exemplos incluem:

• Estilo de tabela
• Realce de sintaxe
• Cores de alerta
• Âncoras de cabeçalho
• Imagens responsivas
• Posição de notas de rodapé
• Fontes de matemática

Duas plataformas podem analisar sintaxe idêntica enquanto produzem apresentações substancialmente diferentes.

Um Modelo de Portabilidade Melhor

Em vez de perguntar se um arquivo é “Markdown válido”, faça quatro perguntas mais estreitas:

1. Em qual dialeto a fonte está escrita?
2. Qual analisador a lê?
3. Quais extensões estão ativadas?
4. Quais transformações de plataforma rodam em seguida?

Por exemplo:

Dialeto: CommonMark mais tabelas GFM
Analisador: Goldmark
Extensões: tabelas, tachado, listas de tarefas, notas de rodapé
Plataforma: Hugo
Processamento adicional: ganchos de renderização e JavaScript Mermaid

Essa descrição é muito mais útil do que dizer “o site usa Markdown”.

Escolhendo um Dialeto por Caso de Uso

Arquivos README

Use GFM.

Arquivos README se beneficiam de:

• Tabelas
• Listas de tarefas
• Código com cercas
• Autolinks
• Tachado
• Referências do GitHub

Evite dependência excessiva de recursos exclusivos do GitHub quando o repositório é espelhado no GitLab, renderizado em um registro de pacotes ou incluído em documentação gerada.

Artigos Técnicos no Hugo

Use Markdown compatível com CommonMark com um conjunto documentado de extensões Goldmark.

Tabelas, cercas de código, notas de rodapé e Mermaid podem ser razoáveis porque você controla o pipeline de compilação. Prefira shortcodes ou ganchos de renderização do Hugo em vez de incorporar grandes quantidades de HTML em bruto.

Mantenha a sintaxe específica do Hugo isolada e fácil de encontrar.

Documentos Acadêmicos

Use Pandoc Markdown.

Citações, processamento de bibliografia, notas de rodapé, metadados, notação matemática, cruzamentos de referência e conversão para PDF ou DOCX justificam a portabilidade reduzida.

Armazene o comando do Pandoc, arquivo de padrões, filtros, bibliografia e modelos ao lado da fonte. O arquivo de fonte sozinho não descreve totalmente a compilação.

Livros e Documentação Longa

O Pandoc Markdown geralmente é o mais forte das três opções quando múltiplos formatos de saída importam.

Listas de definições, citações, atributos, metadados e transformações estruturadas se tornam mais importantes à medida que a complexidade do documento cresce.

Para documentação apenas para web hospedada em um repositório Git, GFM ou um gerador de documentação baseado em CommonMark pode permanecer mais simples.

Notas e Bases de Conhecimento Pessoal

Use a sintaxe nativa da aplicação de notas selecionada quando os recursos da aplicação proporcionam valor real.

Links wiki, incorporados e chamadas do Obsidian são úteis dentro de um cofre. Trate a exportação como um processo de compilação, em vez de assumir que os arquivos brutos já são publicações portáveis.

Documentação Compartilhada entre Sistemas Desconhecidos

Use um subconjunto conservador do CommonMark.

Evite:

• Links wiki
• Alertas de plataforma
• Atributos de cabeçalho
• Citações
• HTML em bruto
• Contêineres personalizados
• Incorporados de aplicação
• Shortcodes

A portabilidade geralmente requer abrir mão de recursos de conveniência.

Regras Práticas para Markdown Portável

Comece com a Estrutura CommonMark

Use CommonMark para o esqueleto do documento:

• Cabeçalhos
• Parágrafos
• Listas
• Links
• Imagens
• Citações em bloco
• Blocos de código

Isso garante que o significado principal sobreviva, mesmo quando extensões opcionais falham.

Adicione Recursos GFM Deliberadamente

Tabelas e listas de tarefas são razoáveis quando todos os destinos importantes as suportam.

Não assuma “a maioria das ferramentas suporta GFM” sem testar o destino exato. Algumas afirmam compatibilidade com GFM enquanto ativam apenas extensões selecionadas.

Isole Extensões de Plataforma

Mantenha a sintaxe específica da plataforma em blocos claramente identificáveis.

Por exemplo, centralize shortcodes do Hugo, citações do Pandoc ou incorporados do Obsidian, em vez de espalhá-los por todos os parágrafos.

O isolamento torna a conversão posterior mais fácil.

Prefira a Degradação Graciosa

Um bloco Mermaid degrada em código fonte legível. Um alerta do GitHub degrada em uma citação em bloco.

Um incorporado wiki pode degradar em um nome de arquivo não explicado, enquanto uma divisão com cerca do Pandoc pode expor pontuação em torno do conteúdo.

Escolha extensões cujo fallback permaneça compreensível.

Não Dependa de IDs de Cabeçalho Gerados Automaticamente

Os algoritmos de âncora de cabeçalho diferem entre GitHub, Hugo, Pandoc e geradores de documentação.

Para links entre documentos, use apenas IDs explícitos suportados pelo renderizador quando o pipeline de destino for controlado. Caso contrário, faça o link para o documento, em vez de para um fragmento gerado.

Mantenha a Configuração de Compilação com o Conteúdo

Extensões do Pandoc, configurações do Hugo, plugins, filtros e integrações de JavaScript determinam como o Markdown se comporta.

Commite arquivos de configuração relevantes com a fonte:

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

Uma extensão .md sozinha não captura o ambiente de publicação. Para uma abordagem estruturada para documentar essas decisões, veja Registros de Decisão para Desenvolvimento Impulsionado por IA.

Teste o Markdown Contra Todos os Destinos Importantes

A pré-visualização visual em um editor não é suficiente. O editor pode suportar um dialeto mais rico do que o renderizador de produção.

Para o Pandoc, teste 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

Avisos e pontuação de fonte visível revelam quais recursos são específicos do dialeto.

Para o Hugo, compile o site de produção:

hugo --gc --minify

Depois, inspecione o HTML gerado, em vez de depender apenas de uma pré-visualização do editor.

Para repositórios, visualize o arquivo commitado na plataforma de hospedagem real. Extensões locais de Markdown no VS Code podem não corresponder ao GitHub ou GitLab.

Solução de Problemas de Divergências Comuns de Renderização

Quando um arquivo que funcionava em uma plataforma quebra em outra, a falha geralmente se enquadra em um punhado de padrões repetíveis. A tabela a seguir lista o sintoma como você realmente o veria, a causa mais provável e um comando ou verificação concreta para confirmar e corrigi-lo.

Este é o primeiro passo mais rápido antes de assumir um “bug” no Markdown — a maioria dessas divergências é uma extensão faltante ou um recurso exclusivo de plataforma, não sintaxe quebrada. Para problemas específicos de cercas de código, como realce de sintaxe faltante ou identificadores de linguagem não suportados, veja o guia dedicado sobre Blocos de Código no Markdown.

Lint no Subconjunto Portátil

Um linter de Markdown não pode garantir compatibilidade com o renderizador, mas pode remover ambiguidade evitável.

Regras úteis incluem:

• Usar estilos de cabeçalho consistentes
• Adicionar linhas em branco ao redor de listas e blocos de código
• Usar código com cercas em vez de código indentado
• Especificar linguagens de cercas de código
• Evitar níveis de cabeçalho pulados
• Usar marcadores de lista consistentes
• Evitar ênfase ambígua em torno de pontuação
• Manter finalizações de linha consistentes
• Validar links e imagens

Para publicação em múltiplos destinos, adicione um teste de compilação para cada renderizador importante, em vez de depender apenas de lint de sintaxe.

Convertendo entre Dialetos com Pandoc

O Pandoc pode normalizar documentos de um dialeto para outro:

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

Ou converter GFM para Pandoc Markdown:

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

Isso é útil, mas a conversão não garante preservar cada recurso.

Perdas potenciais incluem:

• Referências específicas da plataforma
• Estilização de chamadas
• Tabelas complexas
• Objetos de aplicação incorporados
• Atributos personalizados
• Comportamento de HTML em bruto
• Sintaxe de plugin
• Renderização de diagramas
• Espaçamento em branco e formatação exatos

O Pandoc preserva a estrutura do documento melhor do que a formatação da fonte original. Trate a conversão como uma etapa de compilação, não como um formador de texto reversível.

Estratégia Recomendada para Sites Hugo

Para um blog técnico no Hugo, a política mais prática é:

1. Use CommonMark para prosa e estrutura principais.
2. Ative um pequeno conjunto documentado de extensões Goldmark.
3. Use tabelas e listas de tarefas estilo GFM onde melhoram a legibilidade.
4. Implemente Mermaid através de um único gancho de renderização ou shortcode consistente.
5. Processe matemática através de um único pipeline documentado de KaTeX ou MathJax.
6. Use front matter do Hugo apenas no início dos arquivos de conteúdo.
7. Prefira ganchos de renderização e shortcodes em vez de HTML em bruto.
8. Mantenha links de fonte como links de Markdown padrão, onde possível.
9. Teste documentos migrados ou de origem externa através do Hugo.
10. Documente qualquer sintaxe que não será renderizada corretamente no GitHub.

Essa abordagem aceita que o conteúdo do Hugo não é universalmente portátil, mantendo a fronteira de portabilidade visível.

A pior abordagem é a mistura acidental de dialetos: alertas do GitHub, incorporados do Obsidian, atributos do Pandoc e shortcodes do Hugo colocados no mesmo documento sem um pipeline de compilação definido.

Tabela de Decisão

Conclusão

CommonMark, GitHub Flavored Markdown e Pandoc Markdown não são versões concorrentes do mesmo produto. Eles resolvem problemas diferentes.

O CommonMark fornece uma fundação de análise confiável. O GFM adiciona recursos práticos para colaboração em software, enquanto o Pandoc Markdown transforma o Markdown em uma língua de fonte rica para publicação e conversão.

A regra mais segura é simples: escreva o dialeto mínimo que satisfaz o destino real. Use CommonMark quando o conteúdo deve viajar, GFM quando a colaboração estilo GitHub é o destino e Pandoc Markdown quando a estrutura do documento e os formatos de saída importam mais do que a renderização universal.

A portabilidade de Markdown não é alcançada evitando cada extensão. É alcançada sabendo quais extensões fazem parte do contrato de fonte e testando-as em cada renderizador que importa.

Referências

• Especificação CommonMark
• Especificação GitHub Flavored Markdown
• Pandoc Markdown
• Documentação Goldmark
• Configuração Goldmark do Hugo
• Escrevendo Expressões Matemáticas no GitHub