GFM vs CommonMark vs Pandoc Markdown: Sintaxe Comparada

O Markdown parece uma única linguagem 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 instável.

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

A escolha entre eles depende de onde o documento deve ser renderizado. Um arquivo README, um post de blog do Hugo e um artigo acadêmico têm 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 seu ambiente-alvo. Para uma referência rápida de sintaxe, o resumo do Markdown cobre os elementos essenciais de formatação.

O Markdown Não É Uma Única Linguagem

A sintaxe original do Markdown foi intencionalmente pequena e vagamente especificada. Isso facilitou a leitura e a implementação, mas diferentes analisadores começaram a interpretar entradas ambíguas de maneiras diferentes.

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 base com várias extensões amplamente utilizadas.

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

Um relacionamento simplificado parece com isto:

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

A Resposta Curta

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

Use o GFM ao escrever arquivos README, pull requests, modelos de issues e documentação técnica destinada principalmente a plataformas compatíveis com o GitHub.

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

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

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

CommonMark: O Núcleo Portátil

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

Ele define como os analisadores devem interpretar:

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

Um documento CommonMark ainda pode se comportar de forma diferente na camada de apresentação. CSS, realce de sintaxe, âncoras de cabeçalho, sanitização 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 do CommonMark

# Implantação 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 delimitado e links comuns, sem depender de extensões específicas de dialetos.

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 na documentação de repositórios e colaboração.

A especificação formal do GFM adiciona:

• Tabelas de pipe
• Itens de lista de tarefas
• Tachado
• Autolinks estendidos
• Restrições em torno de algumas tags HTML brutas

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

Tabelas GFM

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

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

Listas de Tarefas GFM

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

A sintaxe de listas de tarefas é útil em issues, pull requests e documentação de projetos. Fora de um renderizador de suporte, ela pode aparecer como uma lista comum contendo colchetes literais.

Tachado GFM

Use o ~~endpoint antigo~~ novo endpoint.

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

Autolinks GFM

O GFM reconhece mais textos parecidos com URLs e e-mails sem exigir colchetes angulares ou sintaxe de link explícita.

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.

Não pertence.

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

• Expressões matemáticas
• Diagramas Mermaid
• Alertas
• Referências a issues e pull requests
• Menções de usuários e equipes
• Referências a commits
• Shortcodes de emoji
• Seções HTML colapsá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 é importante porque outro renderizador pode alegar corretamente compatibilidade com GFM sem implementar o renderizador de matemática do GitHub, a integração Mermaid, referências de issues ou estilização de alertas.

Diagramas Mermaid do GitHub

O GitHub renderiza um bloco de código delimitado marcado com 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 Mermaid, veja o Guia Rápido de Diagramas Mermaid.

Expressões Matemáticas do GitHub

O GitHub suporta expressões matemáticas inline e em bloco usando delimitadores de cifrão e formas adicionais de escape.

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

$$
C = 2nlhd
$$

A 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 matemático do Pandoc.

Alertas do GitHub

O GitHub suporta citações de bloco no estilo de 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 de 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 Linguagem de Documento

O Pandoc Markdown é projetado para conversão de documentos, não para um site específico. Ele usa o Markdown como sintaxe fonte para produzir HTML, PDF, DOCX, EPUB, LaTeX, apresentações e outros formatos.

Seu leitor de Markdown padrão 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ção
• Notação matemática
• Identificadores e atributos de cabeçalho
• Atributos de bloco de código
• Divisões delimitadas
• Span delimitados por colchetes
• Sobrescrito e subscrito
• Tachado
• Blocos de linha
• Listas de exemplo numeradas
• LaTeX bruto
• HTML 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é do Pandoc

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

[^dialetos]: 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, não uma garantia formal do GFM. Um renderizador que alega apenas compatibilidade com CommonMark ou GFM pode não suportá-los.

Citações do 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 artigo.md \
  --citeproc \
  --bibliography referencias.bib \
  --csl ieee.csl \
  -o artigo.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ção compatível. A flexibilidade do lado do leitor do Pandoc também sustenta fluxos de trabalho 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 do 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 autoria estendido para conversão de documentos.

As listas de definição são úteis em manuais, glossários e livros técnicos. Elas normalmente se degradam mal em renderizadores que não as suportam, pois as linhas de dois pontos permanecem visíveis como texto simples.

Atributos de Cabeçalho do Pandoc

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

O Pandoc interpreta as chaves como um identificador explícito e uma lista de classes. 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 colocada em um documento esperado para ser renderizado em todos os lugares.

Divisões Delimitadas do 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 possa suportar o recurso. Significa que o recurso não é garantido pela especificação formal desse dialeto.

Qual Sintaxe Funciona no GitHub?

Para arquivos README, issues, pull requests, 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 issues e apresentação de alertas podem não sobreviver fora do GitHub.

Para arquivos de repositório que também são publicados em outro lugar, 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 de Markdown padrão. 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 recursos funcionam bem:

• Estrutura CommonMark
• Blocos de código delimitados
• Tabelas de pipe
• Tachado
• Listas de tarefas
• IDs de cabeçalho automáticos
• Realce de sintaxe
• Notas de rodapé quando a extensão está habilitada
• Listas de definição quando habilitadas
• Substituições tipográficas quando habilitadas

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

• Front matter
• Shortcodes
• Render hooks
• Recursos de página
• Funções de referência interna
• Processamento de modelo
• Configuração do site

Esses recursos do Hugo não viajam com o arquivo 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 Markdown

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

---
title: "Compatibilidade do Markdown"
description: "Compare dialetos e renderizadores de Markdown."
date: 31/07/2026
tags:
  - Markdown
  - documentação
---

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.

A mesma sintaxe pode, portanto, ser reconhecida em mais de uma ferramenta sem ter a mesma semântica.

HTML Bruto no Hugo

O Goldmark não renderiza HTML 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 bruto esteja habilitada ou o conteúdo seja implementado através de um shortcode ou render hook.

Para um blog técnico controlado, habilitar HTML 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 mermaid delimitado ainda é apenas um bloco de código, a menos que o tema do Hugo, render hook, shortcode ou pipeline de JavaScript o transforme em um diagrama.

O GitHub e o Hugo podem, portanto, aceitar uma 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 entrada.md
pandoc --from=commonmark entrada.md
pandoc --from=gfm entrada.md
pandoc --from=commonmark_x entrada.md

Esta é uma das funcionalidades 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 habilitar ou desabilitar extensões individuais:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  entrada.md \
  -o saida.html

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

pandoc \
  --from=commonmark+footnotes \
  entrada.md \
  -o saida.html

Você pode inspecionar as 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 build e arquivos de padrão fazem parte da especificação do documento.

Qual Sintaxe Funciona no Obsidian?

O Obsidian armazena notas como arquivos Markdown, mas seu modelo de autoria inclui vários recursos específicos do aplicativo.

Exemplos comuns incluem:

• Links Wiki
• Notas incorporadas
• Arquivos incorporados
• Alertas (Callouts)
• Referências de bloco
• Tags
• Propriedades
• Realce
• Comentários
• Consultas Dataview de plugins
• Links URI específicos do aplicativo

Um link Wiki como:

[[Compatibilidade do Markdown]]

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

Um embed é ainda mais específico do aplicativo:

![[tabela-compatibilidade]]

O conteúdo referenciado não está presente no próprio arquivo. Portanto, exportar ou publicar a nota requer uma etapa de expansão que resolva o embed.

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

Qual Sintaxe Funciona no GitLab?

O GitLab Flavored Markdown usa o CommonMark como seu núcleo e inclui recursos do GFM, como tabelas e listas de tarefas. Em seguida, ele adiciona comportamento específico do GitLab, incluindo referências cruzadas, 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 grandes danos.

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

Matriz de Suporte da 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êntica. Significa que o ambiente reconhece o recurso geral.

Sintaxe Que Geralmente É Segura em Todas as Partes

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 delimitados usando crases
• Código inline usando crases
• Ênfase usando *texto*
• Ênfase forte usando **texto**
• Links comuns
• Imagens comuns
• Citações de bloco
• Quebras temáticas
• Autolinks explícitos com colchetes angulares

Um documento intencionalmente conservador pode parecer com isto:

# Guia de Implantação

Este guia explica como implantar o serviço.

## Requisitos

- Docker
- Linux
- Uma GPU suportada

## 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, callouts 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 de Pipe

As tabelas de pipe são bem suportadas por ferramentas orientadas ao GFM, mas não pelo CommonMark estrito.

Uma tabela pode se degradar em texto ilegível ao passar 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 build.

Notas de Rodapé

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

Diferentes ferramentas podem:

• Suportar apenas um formato de nota de rodapé
• Colocar notas de rodapé de maneira diferente
• Gerar identificadores diferentes
• Rejeitar notas de rodapé multi-parágrafo
• Renderizar a fonte literalmente

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

IDs e Atributos de Cabeçalho

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

## Instalação {#instalacao .procedimento}

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

Também evite codificar links para IDs de cabeçalho gerados automaticamente, a menos que cada destino use as mesmas regras de slugificação.

Callouts e Alertas

GitHub, Obsidian, GitLab, MkDocs, Docusaurus e temas do Hugo podem suportar blocos semelhantes a callouts, mas muitas vezes usam sintaxes diferentes.

Um fallback portátil é uma citação de 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

Os links Wiki são concisos dentro de ferramentas de gerenciamento de conhecimento:

[[Cache KV]]

Eles são uma sintaxe de intercâmbio ruim, pois o caminho do destino, nome do arquivo, regras de cabeçalho e comportamento de resolução pertencem ao aplicativo.

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

[Cache KV](cache-kv.md)

HTML Bruto

O HTML 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
• Escapá-lo
• Sanitizar elementos selecionados
• Permitir blocos, mas não elementos inline
• Recusar a análise de Markdown dentro do HTML
• Passá-lo inalterado apenas em modo confiável

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

Notação Matemática

A matemática delimitada por cifrões é popular, mas não universalmente interpretada.

A fonte:

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

pode se tornar:

• Matemática renderizada
• Texto comum com cifrões
• Ênfase incorreta
• Entrada para um analisador de matemática diferente

Escolha um pipeline de matemática e teste-o em cada ambiente-alvo.

Blocos de Diagrama Mermaid e Outros

Uma cerca de código Mermaid é sintaticamente segura, pois renderizadores não suportados normalmente a exibem como código.

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

Esta é uma degradação graciosa, não compatibilidade verdadeira.

As Três Camadas de Compatibilidade do 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 delimitadas.

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 issue
• Processar shortcodes
• Gerar um índice

Camada 3: Compatibilidade de Apresentação

O resultado parece e se comporta apropriadamente?

Exemplos incluem:

• Estilização de tabela
• Realce de sintaxe
• Cores de alerta
• Âncoras de cabeçalho
• Imagens responsivas
• Posicionamento de notas de rodapé
• Fontes matemáticas

Duas plataformas podem analisar sintaxe idêntica enquanto produzem apresentação substancialmente diferente.

Um Modelo de Portabilidade Melhor

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

1. Em qual dialeto a fonte está escrita?
2. Qual analisador a lê?
3. Quais extensões estão habilitadas?
4. Quais transformações de plataforma são executadas posteriormente?

Por exemplo:

Dialeto: CommonMark mais tabelas GFM
Analisador: Goldmark
Extensões: tabelas, tachado, listas de tarefas, notas de rodapé
Plataforma: Hugo
Processamento adicional: render hooks 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.

Os arquivos README se beneficiam de:

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

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

Artigos Técnicos do 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 build. Prefira shortcodes do Hugo ou render hooks em vez de incorporar grandes quantidades de HTML 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, referências cruzadas e conversão para PDF ou DOCX justificam a portabilidade reduzida.

Armazene o comando Pandoc, arquivo de padrão, filtros, bibliografia e modelos ao lado da fonte. O arquivo de fonte sozinho não descreve totalmente o build.

Livros e Documentação de Longo Formato

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

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

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

Notas e Bases de Conhecimento Pessoal

Use a sintaxe nativa do aplicativo de notas selecionado quando os recursos do aplicativo fornecerem valor real.

Links Wiki, embeds e callouts 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 em Sistemas Desconhecidos

Use um subconjunto conservador do CommonMark.

Evite:

• Links Wiki
• Alertas de plataforma
• Atributos de cabeçalho
• Citações
• HTML bruto
• Contêineres personalizados
• Embeds de aplicativo
• Shortcodes

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

Regras Práticas para Markdown Portátil

Comece com a Estrutura CommonMark

Use o CommonMark para o esqueleto do documento:

• Cabeçalhos
• Parágrafos
• Listas
• Links
• Imagens
• Citações de 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 alvos importantes as suportam.

Não assuma que “a maioria das ferramentas suporta GFM” sem testar o alvo exato. Algumas alegam compatibilidade com GFM enquanto habilitam 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 embeds do Obsidian, em vez de espalhá-los em cada parágrafo.

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

Prefira a Degradação Graciosa

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

Um embed Wiki pode se degradar em um nome de arquivo não explicado, enquanto uma divisão delimitada do Pandoc pode exp pontuação ao redor do conteúdo.

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

Não Dependam 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 IDs explícitos suportados pelo renderizador apenas quando o pipeline de destino for controlado. Caso contrário, vincule ao documento em vez de a um fragmento gerado.

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

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

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

conteudo/
  artigo.md
pandoc.yaml
referencias.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 Cada Alvo Importante

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 artigo.md -o commonmark.html
pandoc --from=gfm artigo.md -o gfm.html
pandoc --from=markdown artigo.md -o pandoc.html

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

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

hugo --gc --minify

Em seguida, 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. As extensões de Markdown locais no VS Code podem não corresponder ao GitHub ou GitLab.

Solucionando Problemas de Inconsistências de Renderização Comuns

Quando um arquivo que funcionou em uma plataforma quebra em outra, a falha geralmente se encaixa em um punhado de padrões repetíveis. A tabela abaixo 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.

Esta é a primeira passagem mais rápida antes de assumir um “bug” do Markdown — a maioria dessas inconsistências é uma extensão ausente ou um recurso exclusivo da plataforma, não sintaxe quebrada. Para problemas específicos de cerca de código, como realce de sintaxe ausente ou identificadores de linguagem não suportados, veja o guia dedicado sobre Blocos de Código 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 delimitado em vez de indentado
• Especificar linguagens de cerca de código
• Evitar níveis de cabeçalho pulados
• Usar marcadores de lista consistentes
• Evitar ênfase ambígua ao redor de pontuação
• Manter finais de linha consistentes
• Validar links e imagens

Para publicação multi-alvo, adicione um teste de build para cada renderizador importante em vez de depender apenas da linting de sintaxe.

Convertendo Entre Dialetos com o Pandoc

O Pandoc pode normalizar documentos de um dialeto para outro:

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

Ou converter GFM para Pandoc Markdown:

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

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

Perdas potenciais incluem:

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

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

Estratégia Recomendada para Sites do Hugo

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

1. Usar CommonMark para prosa e estrutura principais.
2. Habilitar um pequeno conjunto documentado de extensões Goldmark.
3. Usar tabelas e listas de tarefas no estilo GFM onde melhoram a legibilidade.
4. Implementar Mermaid através de um render hook ou shortcode consistente.
5. Lidar com matemática através de um pipeline documentado de KaTeX ou MathJax.
6. Usar front matter do Hugo apenas no início dos arquivos de conteúdo.
7. Preferir render hooks e shortcodes em vez de HTML bruto.
8. Manter links de fonte como links Markdown padrão, sempre que possível.
9. Testar documentos migrados ou obtidos externamente através do Hugo.
10. Documentar qualquer sintaxe que não será renderizada corretamente no GitHub.

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

A pior abordagem é a mistura acidental de dialetos: alertas do GitHub, embeds do Obsidian, atributos do Pandoc e shortcodes do Hugo colocados no mesmo documento sem um pipeline de build 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 linguagem de fonte rica para publicação e conversão.

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

A portabilidade do Markdown não é alcançada evitando cada extensão. É alcançada sabendo quais extensões fazem parte do contrato da 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