Guia de Sintaxe Estendida Markdown: Tabelas, Notas de Rodapé, Listas de Tarefas e Mais

A sintaxe estendida markdown é o conjunto de elementos de formatação adicionados depois que John Gruber publicou a especificação original em 2004. A especificação de 2004 definiu 11 elementos básicos e deixou de fora tabelas, notas de rodapé, listas de tarefas e tachado. Projetos posteriores preencheram essas lacunas: o MultiMarkdown trouxe tabelas e notas de rodapé em 2005, o Pandoc chegou em 2006 com o maior conjunto de extensões entre todos os processadores, o CommonMark padronizou o núcleo em 2014 deixando espaço para extensões, e o GitHub publicou a especificação GFM em 2017. Todo elemento desta página renderiza na visualização ao vivo do editor, então uma colagem de 5 segundos mostra ao usuário se o aplicativo de destino aceita o elemento.

Matriz de Suporte

Nenhum aplicativo suporta todos os 12 elementos estendidos, então verifique o suporte do destino antes de publicar. Os 4 destinos mais comuns diferem bastante:

Um atalho prático: tabelas markdown, blocos de código cercados, tachado e listas de tarefas renderizam em quase qualquer lugar. Listas de definição, realce, subscrito e sobrescrito são os 4 elementos com maior chance de falhar.

Tabelas

Uma tabela markdown separa colunas com barras verticais (pipes) e marca a linha de cabeçalho com uma linha divisória de 3 ou mais hífens. Os pipes externos são opcionais na maioria dos parsers, mas melhoram a compatibilidade, então mantenha todos.

| Feature | Status |
| :------ | -----: |
| Export  | Done   |
| Sync    | Open   |

Dois-pontos na linha divisória controlam o alinhamento. :--- alinha a coluna à esquerda, :---: centraliza e ---: empurra para a direita. O parser aplica o alinhamento a todas as células da coluna. A quantidade de hífens não precisa coincidir entre as colunas. Para imprimir um pipe literal dentro de uma célula, escreva a entidade HTML |; o GitHub também aceita o escape com barra invertida \|. As células aceitam formatação inline, como negrito e trechos de código, mas nunca elementos de bloco, como listas ou títulos.

O MultiMarkdown introduziu a sintaxe em 2005 e o GFM a adotou em 2017. GitHub, GitLab, Obsidian e Pandoc renderizam tabelas markdown. O Discord não.

Blocos de Código Cercados

Um bloco de código cercado abre e fecha com 3 crases (backticks) e dispensa indentação, ao contrário dos blocos de código com 4 espaços da especificação de 2004. Três tis funcionam como cerca alternativa na maioria dos parsers.

```python
def total(items):
    return sum(items)
```

Um identificador de linguagem colocado logo após a cerca de abertura ativa o realce de sintaxe. O highlight.js, biblioteca por trás de muitos renderizadores web, traz definições para cerca de 200 linguagens, e identificadores comuns incluem python, js, json, bash e sql. Para exibir um bloco de código dentro de outro bloco de código, use 4 crases na cerca externa.

O suporte é o mais amplo entre todos os elementos estendidos. GitHub, Obsidian, Discord e Pandoc renderizam blocos cercados, e os 4 aplicam o realce de linguagem.

Notas de Rodapé

Uma nota de rodapé tem 2 partes: um marcador de referência no corpo do texto, escrito como [^1], e uma definição colocada em qualquer lugar do arquivo, escrita como [^1]: seguida da nota. O renderizador reúne todas as definições no fim da página e vincula cada par nas duas direções.

The claim has a published source.[^1]

[^1]: Smith, 2024, p. 41.

Os identificadores podem ser palavras além de números, e [^note] se comporta exatamente como [^1], porque a numeração de saída segue a ordem do documento, não o rótulo. Uma nota de rodapé comporta vários parágrafos quando os parágrafos extras ficam indentados 4 espaços sob a definição.

O MultiMarkdown lançou as notas de rodapé markdown em 2005, Pandoc e Obsidian as suportam por completo, e o GitHub adicionou a renderização de notas de rodapé em 2021. O Discord não tem suporte a notas de rodapé.

IDs de Título

Um ID de título personalizado fica entre chaves no fim da linha do título, e ## Refund Policy {#refunds} gera o elemento HTML h2 com id="refunds". O ID vira uma âncora estável para links e CSS.

## Refund Policy {#refunds}

Jump straight to [the refund policy](#refunds).

O link é um link markdown padrão com uma cerquilha (hash) e o ID como alvo. Páginas externas chegam ao mesmo ponto quando #refunds é acrescentado à URL completa da página.

Pandoc e PHP Markdown Extra interpretam a forma com chaves. O GitHub a ignora, mas gera IDs automáticos a partir do texto do título, então um link para #refund-policy ainda funciona por lá. O Obsidian usa o próprio padrão [[Note#Heading]] para links de título. O Discord renderiza títulos em mensagens, mas não tem sistema de âncoras.

Listas de Definição

Uma lista de definição associa um termo a 1 ou mais definições: o termo fica sozinho em uma linha, e cada definição começa na linha seguinte com dois-pontos e um espaço.

Markdown
: A plain-text formatting syntax released in 2004.

Parser
: Software that converts markdown into HTML.
: Also called a processor.

A saída é um elemento <dl> de verdade, com filhos <dt> e <dd>, o que importa para glossários e para leitores de tela. Linhas de dois-pontos empilhadas dão várias definições ao mesmo termo.

O suporte é restrito. O PHP Markdown Extra definiu a sintaxe, e tanto o Pandoc quanto o MultiMarkdown a interpretam. GitHub e Obsidian imprimem as linhas de dois-pontos como texto puro, e o Discord faz o mesmo. HTML <dl> puro é o fallback confiável no GitHub.

Tachado

O tachado envolve o texto com 2 tis de cada lado, então like this renderiza como texto riscado. O elemento vem do GFM, e a saída HTML é um elemento <del>.

~~Ship v2 on Friday.~~ Moved to Monday.

O GitHub também aceita um único til de cada lado. Fique com 2 pela portabilidade, porque o til único significa subscrito no Pandoc, e uma diferença de 1 caractere inverte o significado.

O suporte é quase universal. GitHub, Obsidian, Discord e Pandoc renderizam o tachado com 2 tis.

Listas de Tarefas

Um item de lista de tarefas markdown começa como um item de lista normal e adiciona colchetes: - [ ] marca uma tarefa aberta e - [x] marca uma tarefa concluída. O espaço dentro dos colchetes vazios é obrigatório.

- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page

O GitHub introduziu a sintaxe em 2013 e tornou as caixas de seleção interativas em issues e pull requests, onde um clique atualiza o markdown subjacente. O GitHub também as contabiliza, então uma issue mostra o progresso como "2 of 3 tasks". O Obsidian renderiza caixas de seleção clicáveis no modo de leitura, e o Pandoc converte listas de tarefas em caixas de seleção HTML. O Discord deixa os colchetes como caracteres digitados.

Emoji

Emoji entram em um arquivo markdown de 2 formas: colando o caractere Unicode diretamente ou digitando um shortcode como :rocket: nos aplicativos que expandem shortcodes. Emoji colados sobrevivem em qualquer arquivo UTF-8, então 🎯 aparece mesmo onde os shortcodes falham.

Release day :tada: went live at 9 am.

Um shortcode envolve o nome de um emoji entre 2 dois-pontos. O GitHub expande aproximadamente 1.800 shortcodes, e o Discord expande o próprio conjunto mais os emojis personalizados de cada servidor. O Obsidian precisa de um plugin da comunidade para shortcodes, mas mostra emoji colados nativamente, e o Pandoc só expande shortcodes com a extensão de emoji ativada. Os nomes variam entre as plataformas, então um shortcode que funciona no GitHub não tem garantia em nenhum outro lugar.

Realce

O realce envolve o texto com 2 sinais de igual, e ==like this== renderiza com fundo de marca-texto, geralmente amarelo. A saída HTML é um elemento <mark>.

The deadline moved to ==14 March== at noon.

Este é um dos elementos estendidos menos portáveis. O Obsidian renderiza por padrão, e o Pandoc interpreta quando a extensão mark está ativada, disponível desde o Pandoc 3.0, de 2023. GitHub e Discord imprimem os sinais de igual literalmente. Onde a sintaxe falha, a tag <mark> funciona em qualquer renderizador que deixa o HTML passar, o que inclui os arquivos readme do GitHub.

Subscrito e Sobrescrito

O subscrito envolve caracteres em tis únicos, como em H2O, e o sobrescrito envolve em acentos circunflexos únicos, como em x^2^. As duas formas vêm do conjunto de extensões do Pandoc, não de algum flavor web comum.

H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.

O Pandoc as converte em elementos <sub> e <sup>. GitHub e Obsidian ignoram as formas com til e circunflexo, mas deixam as tags HTML passarem, então H₂O funciona nos dois. O Discord não suporta nenhuma das duas. Cuidado com a colisão do til: um aplicativo com tachado de til único vai riscar o seu subscrito em vez de rebaixá-lo.

Links Automáticos de URL

O link automático de URL transforma um endereço puro como https://example.com em um link clicável, sem exigir a sintaxe de colchetes. O GFM formalizou o comportamento como a extensão autolink na especificação de 2017.

Full docs at https://example.com/docs

GitHub e Discord transformam URLs puras em links, e o Obsidian faz o mesmo no modo de leitura. O Pandoc mantém o comportamento desligado, a menos que a extensão autolink_bare_uris seja ativada. Para impedir que uma URL vire link, envolva-a em crases; trechos de código nunca viram link, então https://example.com permanece texto puro em amostras de configuração e domínios de exemplo.

Perguntas frequentes

A sintaxe estendida faz parte do markdown oficial?

Não. A especificação de 2004 define 11 elementos básicos, e todo elemento desta página vem de flavors e processadores posteriores. O markdown não tem órgão regulador, e é por isso que o suporte muda de um aplicativo para outro.

Qual flavor de markdown suporta mais sintaxe estendida?

O Pandoc suporta a maior variedade, com mais de 30 extensões de sintaxe opcionais, e interpreta todos os 12 elementos desta página. O GFM é o alvo mais prático para publicação na web, porque GitHub, GitLab e a maioria dos editores modernos o seguem.

Por que uma tabela renderiza no GitHub, mas não no Discord?

O Discord implementa um subconjunto restrito de markdown feito para chat e deixa de fora tabelas, notas de rodapé, listas de tarefas e listas de definição. Seu subconjunto cobre negrito, itálico, tachado, títulos e blocos de código cercados. Conteúdo destinado ao Discord deve ficar dentro desses 5 elementos.

Como testar a sintaxe estendida antes de publicar?

Cole o elemento na visualização ao vivo do editor online, que renderiza GFM mais notas de rodapé em menos de 1 segundo. Para qualquer outro destino, cole uma amostra de 2 linhas no próprio aplicativo alvo; a matriz de suporte cobre os 4 casos mais comuns.