CommonMark vs GFM: Tabelas fazem parte da especificação principal?

TL;DR — CommonMark vs GFM

• O CommonMark é a especificação padrão do Markdown. Ele define apenas a sintaxe principal — títulos, listas, ênfase, links, imagens, código e citações — e deixa de fora as extensões de propósito.
• O GFM (GitHub Flavored Markdown) é um dialeto que a própria especificação descreve como um "superconjunto estrito" do CommonMark. Ele adiciona cinco extensões por cima: tabelas, texto tachado, listas de tarefas, autolinks estendidos e HTML bruto não permitido.
• Os recursos do GitHub.com que as pessoas associam ao GitHub Markdown — alertas como [!NOTE], atalhos de emoji, @menções, referências a issues, diagramas Mermaid, fórmulas matemáticas, notas de rodapé — não fazem parte da especificação do GFM. Eles são uma camada do GitHub.com e, em geral, não funcionam fora do GitHub.
• Se uma quebra de linha simples (soft line break) vira ou não um <br> é igual no CommonMark e na especificação do GFM: não vira. Apenas as caixas de comentário de issue/PR do GitHub.com transformam uma única quebra de linha em uma quebra de linha — arquivos .md no GitHub ainda precisam de dois espaços ao final, uma barra invertida ou um <br> literal.
• Se você não tem certeza de qual dialeto usar: o CommonMark puro é o mais portável, as extensões do GFM são seguras para plataformas no estilo GitHub e os recursos exclusivos do GitHub.com devem ser tratados como passíveis de quebrar em outros lugares.
• O conversor Markdown para HTML do FormatArc oferece suporte às extensões GFM (tabelas, texto tachado, listas de tarefas, autolinks). Você também pode usá-lo para verificar se o seu Markdown depende de sintaxe exclusiva do GFM.

Resposta curta: as tabelas não fazem parte da especificação principal do CommonMark. Elas são definidas na especificação do GFM como uma extensão, junto com texto tachado, listas de tarefas, autolinks estendidos e as regras de HTML bruto não permitido.

Como CommonMark e GFM se relacionam — o GFM é construído sobre o CommonMark

O CommonMark é o projeto que pegou a gramática originalmente ambígua do Markdown e a reescreveu com precisão, acompanhada de uma suíte de testes. O objetivo é eliminar as diferenças entre implementações para que qualquer parser em conformidade produza a mesma saída. Como especificação, ele evita extensões de propósito e define apenas as construções principais: títulos, parágrafos, listas, links, imagens, ênfase, código e citações.

O GFM (GitHub Flavored Markdown) é o dialeto de Markdown que o GitHub usa, e a própria especificação do GFM o descreve como um "superconjunto estrito" do CommonMark. Em termos de especificação, isso significa:

• Qualquer documento CommonMark válido é renderizado de forma idêntica por um parser GFM.
• O GFM apenas adiciona um punhado de extensões ao CommonMark; ele não altera a sintaxe principal.

A palavra "superconjunto" se aplica ao que a especificação do GFM define. Quando você leva em conta a renderização real do GitHub.com, as implementações de bibliotecas individuais e a revisão mais recente do CommonMark, surgem casos extremos. Este artigo mantém separados "as extensões definidas pela especificação do GFM" e "os recursos que o GitHub.com adiciona por conta própria".

Tabela comparativa — CommonMark vs GFM

A chave está nas três colunas. As tabelas, o texto tachado e as demais extensões do GFM funcionam em qualquer parser compatível com GFM, não apenas no GitHub. Alertas, emoji e notas de rodapé não fazem parte da especificação do GFM, então só têm garantia de funcionamento no GitHub.com (ou em plataformas que o copiam).

Tabelas no CommonMark — a especificação principal não as define

A especificação do CommonMark exclui deliberadamente as tabelas da sintaxe principal. As tabelas com pipes e hifens (| col | col |) são definidas apenas na especificação do GFM, onde a seção tem literalmente o título "Tables (extension)" — o próprio GFM marca as tabelas como uma extensão, não como uma construção principal. O mesmo rótulo "(extension)" se aplica a texto tachado, listas de tarefas, autolinks estendidos e às regras de HTML bruto não permitido.

Então um renderizador que segue apenas o CommonMark (sem extensões habilitadas) exibe | col | como um parágrafo com pipes literais; um renderizador compatível com GFM interpreta a mesma entrada como uma <table>. É por isso também que discussões antigas no fórum do CommonMark e issues como a commonmark-spec#393 continuam tratando as tabelas como algo fora do escopo da especificação principal.

Para verificar se um renderizador específico trata as tabelas como uma extensão do GFM, cole uma tabela de duas linhas no Markdown para HTML e procure por <table> na saída.

O que realmente muda quando você converte para HTML

Um parser que segue apenas o CommonMark e um parser compatível com GFM produzem HTML diferente a partir do mesmo Markdown. Compare esta entrada:

| Product | Stock |
| --- | --- |
| Apple | 3 |

~~Sold out~~ — back in stock

- [x] Confirm restock
- [ ] Update price tags

Um parser que segue apenas o CommonMark deixa | Product | Stock | como um parágrafo comum com pipes literais, mantém os tils de ~~Sold out~~ como texto em vez de <del> e renderiza - [x] como um item de lista comum. Um parser compatível com GFM produz HTML com <table>, <del> e <input type="checkbox">.

Por isso, quando "o Markdown parece quebrado", a causa costuma ser uma incompatibilidade de dialeto entre plataformas. Para verificar se o seu Markdown depende de extensões do GFM, cole-o no Markdown para HTML e observe a saída.

As 5 extensões que o GFM adiciona ao CommonMark

Tabelas

Tabelas montadas com pipes | e hifens -. O CommonMark não tem sintaxe de tabelas, então as tabelas são uma extensão do GFM, definida na especificação do GFM em Tables (extension) (GFM spec §4.10). Um renderizador que segue apenas o CommonMark deixa os pipes como texto. Para marcadores de alinhamento (:--- / :---: / ---:), escape de pipes dentro de células e outros detalhes, veja Sintaxe de tabelas em Markdown.

Texto tachado

~~texto a tachar~~ vira um elemento <del>. Envolver o texto em tils duplos é uma extensão do GFM e não faz parte do CommonMark — veja a seção Strikethrough (extension) da especificação do GFM (GFM spec §6.5).

Listas de tarefas

Comece um item de lista com - [ ] (não marcado) ou - [x] (marcado) e ele é renderizado como uma caixa de seleção. A sintaxe é definida na seção Task list items (extension) da especificação do GFM (GFM spec §5.3). No GitHub você pode clicar na caixa de seleção no corpo de uma issue ou PR para alterná-la, mas esse comportamento interativo é um recurso do GitHub.com — um renderizador de HTML comum produz uma caixa de seleção estática.

Autolinks estendidos

Escreva https://example.com diretamente e ele vira um link automaticamente. No CommonMark é preciso envolver uma URL entre sinais de menor e maior (<https://example.com>), mas o GFM também detecta URLs sem marcação e as transforma em links. O comportamento das URLs sem marcação é especificado na seção Autolinks (extension) da especificação do GFM (GFM spec §6.9), que é distinta dos autolinks com sinais de menor e maior do próprio CommonMark.

HTML bruto não permitido

Tanto o CommonMark quanto o GFM permitem que você incorpore HTML bruto dentro do Markdown. A diferença é que o GFM desabilita um pequeno conjunto de tags — <script>, <iframe>, <style> e algumas outras — como "HTML bruto não permitido". Além disso, o GitHub.com executa um sanitizador próprio e mais rígido (removendo atributos e mais). O Markdown para HTML do FormatArc faz apenas a conversão de sintaxe, então, se você converter uma entrada não confiável, sanitize o HTML de saída separadamente.

Onde cada regra é definida — as próprias especificações

Se você quiser verificar qualquer um dos pontos acima na fonte, vá direto às especificações em vez de a um resumo de terceiros:

• A sintaxe principal é definida pela especificação do CommonMark (de John MacFarlane). Ela cobre títulos, parágrafos, listas, links, imagens, ênfase, código e citações, e explicitamente não define tabelas, texto tachado, listas de tarefas nem autolinks de URLs sem marcação.
• As quatro extensões do GFM discutidas aqui têm, cada uma, sua própria seção na especificação do GitHub Flavored Markdown, e todas levam o rótulo "(extension)" no título:
  • Tables (extension) — GFM spec §4.10
  • Task list items (extension) — GFM spec §5.3
  • Strikethrough (extension) — GFM spec §6.5
  • Autolinks (extension) — GFM spec §6.9

O rótulo "(extension)" em cada título do GFM é a forma como a própria especificação marca esses recursos como adições ao CommonMark, e não como sintaxe principal. As regras de HTML bruto não permitido também são definidas na especificação do GFM, na seção Disallowed Raw HTML (extension).

Recursos que são do GitHub.com, não da especificação do GFM

Estes são apresentados com frequência como "GitHub Markdown", mas não fazem parte da especificação do GFM. Trate-os como funcionando apenas no GitHub.com (e em alguns serviços que o imitam).

• Alertas — > [!NOTE] / > [!TIP] / > [!IMPORTANT] / > [!WARNING] / > [!CAUTION]. Renderizam como destaques coloridos.
• Atalhos de emoji — sintaxe :nome:, no estilo :smile:. O Markdown padrão não tem o conceito de emoji.
• @menções / referências a issues e PRs / SHAs de commit — @usuario, #123 e hashes de commit viram links. Eles só fazem sentido dentro do contexto de um repositório.
• Diagramas Mermaid e fórmulas matemáticas — blocos de código ```mermaid e fórmulas $...$. Outra adição do pipeline de renderização do GitHub.com.
• Notas de rodapé — sintaxe [^1]. O GitHub.com oferece suporte a elas, mas elas não fazem parte da especificação do GFM. Algumas ferramentas (como o remark-gfm ou o Goldmark do Hugo) habilitam notas de rodapé junto com as extensões no estilo GFM, mas isso é uma escolha de cada implementação.

Leve o Markdown que usa esses recursos para um contexto fora do GitHub — um blog onde você colou um README, uma ferramenta de documentação — e ele geralmente aparece como texto simples. Trate-os como sintaxe exclusiva do GitHub.com.

Quebras de linha (hard line break) funcionam de forma diferente

Este é um ponto comum de confusão. Tanto no CommonMark quanto na especificação do GFM, uma quebra de linha simples dentro de um parágrafo (uma soft line break) não vira um <br> — as linhas se juntam em um único parágrafo. Para forçar um <br>, você coloca dois espaços ao final, uma barra invertida \ ao final ou uma tag <br> literal. Isso é idêntico no CommonMark e no GFM.

A exceção são as caixas de comentário de issue/PR/discussion do GitHub.com, configuradas para transformar uma única quebra de linha diretamente em um <br>. No mesmo GitHub, os arquivos .md (READMEs, documentação) seguem o comportamento padrão do CommonMark/GFM e ainda precisam de dois espaços ou \. "As quebras de linha funcionaram em um comentário do GitHub, mas não no meu README" é exatamente isso.

Quais plataformas e ferramentas usam cada dialeto

Mais precisamente: de qual opção — "CommonMark puro", "CommonMark + extensões GFM" ou "dialeto próprio" — cada ferramenta mais se aproxima. Uma lista representativa:

"Suporte a GFM" não significa necessariamente que a ferramenta também oferece suporte aos alertas ou emoji do GitHub.com. Por outro lado, uma ferramenta "apenas CommonMark" normalmente consegue obter as extensões do GFM com a adição de um plugin. Na dúvida, consulte a documentação da biblioteca ou serviço que você usa para descobrir "quais extensões estão habilitadas".

Como verificar se o seu ambiente oferece suporte a GFM

Você pode chegar a uma resposta aproximada sem nenhuma investigação profunda:

• Escreva uma tabela (| col |), texto tachado (~~texto~~) e uma lista de tarefas (- [ ]) e veja se cada um deles é renderizado. Se forem, as extensões GFM estão ativas.
• Se você usa uma biblioteca, verifique a configuração dela. O marked precisa de gfm: true, o remark precisa do plugin remark-gfm e o markdown-it habilita tabelas e texto tachado do GFM por padrão.
• Para geradores de sites estáticos, verifique o arquivo de configuração. O Hugo tem markup.goldmark.extensions, o Astro tem markdown.remarkPlugins (procure por remark-gfm) e assim por diante.

Se você só quer saber se um arquivo Markdown específico depende das extensões do GFM, cole-o no Markdown para HTML e veja se as tabelas e o texto tachado viram HTML.

Em qual dialeto você deve escrever?

• O CommonMark puro é o mais portável. Ele é renderizado da forma que você pretendia em praticamente todos os renderizadores.
• Se você tem como alvo o GitHub ou plataformas no estilo GitHub (GitLab, a maioria das ferramentas de documentação), as extensões do GFM (tabelas, texto tachado, listas de tarefas, autolinks) estão de bom tamanho. Esse é o padrão prático.
• Alertas ([!NOTE] etc.), atalhos de emoji, @menções, Mermaid e notas de rodapé devem ser usados "partindo do princípio de que vão quebrar fora do GitHub.com". São úteis em um README, mas, colados em um blog, viram texto simples.
• Se a portabilidade importa, evite misturar HTML bruto. Tanto no CommonMark quanto no GFM, documentos com HTML bruto estão sujeitos a sanitização e a comportamentos específicos de cada renderizador.

Qual dialeto o conversor do FormatArc usa?

O Markdown para HTML do FormatArc executa o marked com gfm: true internamente. Então:

• As extensões da especificação do GFM (tabelas, texto tachado, listas de tarefas, autolinks estendidos) são convertidas direto para HTML.
• Uma quebra de linha simples dentro de um parágrafo segue o comportamento breaks: false — ela não vira um <br>. Igual ao CommonMark/à especificação do GFM e diferente do comportamento das caixas de comentário do GitHub.com.
• Recursos exclusivos do GitHub.com — alertas como [!NOTE], atalhos de emoji, @menções, Mermaid, notas de rodapé — não são suportados, porque não fazem parte da especificação do GFM.

A ferramenta inversa, HTML para Markdown, gera um Markdown parecido com GFM que inclui tabelas e texto tachado. Ambas rodam inteiramente no navegador, sem cadastro e sem upload, então colar um documento interno não publicado não envia nada para lugar nenhum.

Para guias de conversão passo a passo, veja Como converter Markdown para HTML e, para o caminho inverso, Como converter HTML para Markdown.

Perguntas frequentes

Devo escrever Markdown em CommonMark ou GFM?

O CommonMark puro é o mais portável. Se você tem como alvo o GitHub ou plataformas no estilo GitHub, as extensões do GFM (tabelas, texto tachado, listas de tarefas, autolinks) estão de bom tamanho. Use recursos exclusivos do GitHub.com, como [!NOTE], partindo do princípio de que vão quebrar fora do GitHub.

O CommonMark tem sintaxe de tabelas?

Não. As tabelas são uma extensão do GFM e não estão na especificação do CommonMark. Um renderizador que segue apenas o CommonMark mostra | col | como texto simples com pipes literais. Para detalhes sobre como escrever tabelas, veja Sintaxe de tabelas em Markdown.

Os alertas [!NOTE] do GitHub funcionam em outras ferramentas?

Em geral, apenas no GitHub.com (e em alguns serviços que o imitam). A especificação do GFM não tem sintaxe de alertas, então outros renderizadores mostram > [!NOTE] como texto dentro de uma citação.

Obsidian e Notion são compatíveis com GFM?

Não totalmente. O Obsidian é baseado em CommonMark, oferece suporte a tabelas e listas de tarefas do GFM e adiciona uma sintaxe própria, como [[wikilinks]]. O Notion tem um dialeto próprio; sua exportação para Markdown é parecida com GFM, mas a sintaxe dentro do editor é específica do Notion. Consulte a documentação de cada ferramenta para saber a sintaxe suportada.

Com qual dialeto o FormatArc converte?

Parecido com GFM. O Markdown para HTML executa o marked com gfm: true, então oferece suporte a tabelas, texto tachado, listas de tarefas e autolinks. As quebras de linha simples não viram <br> (igual ao CommonMark/à especificação do GFM). Recursos exclusivos do GitHub.com — alertas, emoji, menções, Mermaid, notas de rodapé — não são suportados.

Artigos relacionados

• Como converter Markdown para HTML — os passos concretos para converter Markdown em HTML, incluindo tabelas e listas de tarefas do GFM.
• Sintaxe de tabelas em Markdown: alinhamento, escape e exemplos para copiar e colar — alinhamento de tabelas GFM, escape de pipes e tratamento de quebras de linha em detalhes.
• Cheatsheet de tabelas GFM — referência de uma página para alinhamento, pipes escapados e resultado renderizado no GitHub / GitLab / Obsidian / Notion.
• Como converter HTML para Markdown — convertendo HTML de páginas web ou exportações do Notion em Markdown parecido com GFM.

Resumo

O CommonMark é a especificação padrão do Markdown; o GFM é um dialeto construído sobre ele com cinco extensões (tabelas, texto tachado, listas de tarefas, autolinks estendidos, HTML bruto não permitido). Os alertas, emoji, @menções, Mermaid e notas de rodapé que você vê no GitHub.com ficam em mais uma camada — a do próprio GitHub.com — e, em geral, não funcionam fora do GitHub.

Se você está em dúvida sobre qual dialeto usar: CommonMark para máxima portabilidade, extensões do GFM para plataformas no estilo GitHub e recursos exclusivos do GitHub.com partindo do princípio de que vão quebrar em outros lugares. Quando quiser verificar se o seu Markdown depende das extensões do GFM, ou simplesmente converter Markdown em HTML, use o Markdown para HTML — ele roda inteiramente no navegador, sem cadastro e sem upload.