Guia de Sintaxe Estendida Markdown: Tabelas, Notas e Mais

A sintaxe estendida markdown é o conjunto de elementos de formatação acrescentados depois de John Gruber publicar a especificação original em 2004. A especificação de 2004 definia 11 elementos básicos e deixava completamente de fora tabelas, notas de rodapé, listas de tarefas e texto rasurado. 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 de qualquer processador, o CommonMark padronizou o núcleo em 2014 com espaço para extensões e o GitHub publicou a especificação GFM em 2017. Todos os elementos desta página são apresentados na pré-visualização em tempo real do editor, pelo que colar um exemplo durante 5 segundos diz-lhe se a app de destino o suporta.

Matriz de Suporte

Nenhuma aplicação suporta os 12 elementos estendidos, por isso confirme o suporte do seu destino antes de publicar. Os 4 destinos mais comuns diferem bastante:

Um atalho prático: tabelas, blocos de código delimitados, texto rasurado e listas de tarefas funcionam em quase todo o lado. Listas de definições, realce, subscrito e sobrescrito são os 4 elementos com maior probabilidade de falhar.

Tabelas

Uma tabela markdown separa as colunas com carateres de pipe e marca a linha de cabeçalho com uma linha divisória de 3 ou mais hífens. Os pipes exteriores são opcionais na maioria dos parsers, mas melhoram a compatibilidade, por isso mantenha-os.

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

Os dois pontos na linha divisória controlam o alinhamento. :--- alinha uma coluna à esquerda, :---: centra-a e ---: empurra-a para a direita. O parser aplica o alinhamento a todas as células dessa coluna. O número de hífens não precisa de coincidir entre 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 code spans, mas nunca elementos de bloco, como listas ou cabeçalhos.

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

Blocos de Código Delimitados

Um bloco de código delimitado abre e fecha com 3 backticks e não precisa de indentação, ao contrário dos blocos de código com 4 espaços da especificação de 2004. Três tis funcionam como delimitador alternativo na maioria dos parsers.

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

Um identificador de linguagem colocado logo a seguir ao delimitador de abertura ativa o realce de sintaxe. O highlight.js, a biblioteca por trás de muitos renderizadores web, inclui definições para cerca de 200 linguagens, e os identificadores mais comuns incluem python, js, json, bash e sql. Para mostrar um bloco de código dentro de outro bloco de código, use 4 backticks no delimitador exterior.

O suporte é o mais amplo de qualquer elemento estendido. GitHub, Obsidian, Discord e Pandoc apresentam todos os blocos delimitados, e os 4 aplicam 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 ponto do ficheiro, escrita como [^1]: seguida da nota. O renderizador reúne todas as definições no fundo da página e liga cada par nos dois sentidos.

The claim has a published source.[^1]

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

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

O MultiMarkdown lançou as notas de rodapé markdown em 2005, o Pandoc e o Obsidian suportam-nas na totalidade e o GitHub acrescentou a apresentação de notas de rodapé em 2021. O Discord não tem qualquer suporte para notas de rodapé.

IDs de Cabeçalhos

Um ID de cabeçalho personalizado fica entre chavetas no fim da linha do cabeçalho, e ## Refund Policy {#refunds} produz o elemento HTML h2 com id="refunds". O ID torna-se uma âncora estável para ligações e CSS.

## Refund Policy {#refunds}

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

A ligação é uma ligação markdown normal com um cardinal e o ID como destino. As páginas externas chegam ao mesmo ponto quando #refunds é acrescentado ao URL completo da página.

O Pandoc e o PHP Markdown Extra interpretam a forma com chavetas. O GitHub ignora-a, mas gera IDs automáticos a partir do texto do cabeçalho, pelo que uma ligação para #refund-policy continua a funcionar lá. O Obsidian usa o seu próprio padrão [[Note#Heading]] para ligações a cabeçalhos. O Discord apresenta cabeçalhos nas mensagens, mas não tem sistema de âncoras.

Listas de Definições

Uma lista de definições associa um termo a 1 ou mais definições: o termo fica sozinho numa 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.

O resultado é um verdadeiro elemento <dl> com filhos <dt> e <dd>, o que faz diferença em glossários e para leitores de ecrã. Linhas de dois pontos empilhadas dão várias definições a um único termo.

O suporte é limitado. O PHP Markdown Extra definiu a sintaxe, e o Pandoc e o MultiMarkdown interpretam-na ambos. O GitHub e o Obsidian imprimem as linhas de dois pontos como texto simples, e o Discord faz o mesmo. O HTML <dl> em bruto é a alternativa fiável no GitHub.

Texto Rasurado

O texto rasurado envolve o texto em 2 tis de cada lado, pelo que like this aparece 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 pelos 2 por questões de portabilidade, porque o til único significa subscrito no Pandoc e uma diferença de 1 caráter inverte o significado.

O suporte é quase universal. GitHub, Obsidian, Discord e Pandoc apresentam todos o rasurado com 2 tis.

Listas de Tarefas

Um item de lista de tarefas começa como um item de lista normal e acrescenta parênteses retos: - [ ] marca uma tarefa em aberto e - [x] marca uma tarefa concluída. O espaço dentro dos parênteses 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 verificação interativas em issues e pull requests, onde um clique do utilizador atualiza o markdown subjacente. O GitHub também as conta, pelo que uma issue mostra o progresso como "2 of 3 tasks". O Obsidian apresenta caixas clicáveis na vista de leitura e o Pandoc converte listas de tarefas em caixas de verificação HTML. O Discord deixa os parênteses como carateres escritos.

Emoji

Os emoji entram num ficheiro markdown de 2 formas: cole o caráter Unicode diretamente ou escreva um shortcode como :rocket: nas aplicações que expandem shortcodes. Os emoji colados sobrevivem em qualquer ficheiro UTF-8, por isso 🎯 aparece mesmo onde os shortcodes falham.

Release day :tada: went live at 9 am.

Um shortcode envolve o nome de um emoji em 2 dois pontos. O GitHub expande cerca de 1.800 shortcodes e o Discord expande o seu próprio conjunto mais os emoji personalizados do servidor. O Obsidian precisa de um plugin da comunidade para shortcodes, mas mostra nativamente os emoji colados, e o Pandoc só expande shortcodes com a sua extensão de emoji ativada. Os nomes variam entre plataformas, pelo que um shortcode que funciona no GitHub não é garantido em mais lado nenhum.

Realce

O realce envolve o texto em 2 sinais de igual, e ==like this== aparece com um fundo estilo marcador, normalmente 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 apresenta-o por predefinição e o Pandoc interpreta-o depois de ativada a extensão mark, disponível desde o Pandoc 3.0 em 2023. O GitHub e o Discord imprimem os sinais de igual tal como estão. Onde a sintaxe falha, a tag <mark> funciona em qualquer renderizador que deixe passar HTML, o que inclui os ficheiros readme do GitHub.

Subscrito e Sobrescrito

O subscrito envolve os carateres em tis únicos, como em H2O, e o sobrescrito envolve-os em acentos circunflexos únicos, como em x^2^. Ambas as formas vêm do conjunto de extensões do Pandoc e não de qualquer flavor web comum.

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

O Pandoc converte-os em elementos <sub> e <sup>. O GitHub e o Obsidian ignoram as formas com til e circunflexo, mas deixam passar as tags HTML, pelo que H₂O funciona em ambos. O Discord não suporta nenhum dos dois. Atenção ao conflito do til: uma app com rasurado de til único vai riscar o seu subscrito em vez de o baixar.

Ligações Automáticas de URL

A ligação automática de URL transforma um endereço simples como https://example.com numa ligação clicável sem qualquer sintaxe de parênteses. O GFM formalizou o comportamento como extensão autolink na sua especificação de 2017.

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

O GitHub e o Discord transformam URLs simples em ligações, e o Obsidian faz o mesmo na vista de leitura. O Pandoc mantém o comportamento desligado a não ser que a extensão autolink_bare_uris seja ativada. Para impedir que um URL se transforme numa ligação, envolva-o em backticks; os code spans nunca criam ligações, pelo que https://example.com fica como texto simples em exemplos 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 todos os elementos desta página vêm de flavors e processadores posteriores. O markdown não tem um organismo regulador, e é por isso que o suporte difere de uma aplicação para outra.

Que flavor de markdown suporta mais sintaxe estendida?

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

Porque é que uma tabela aparece no GitHub mas não no Discord?

O Discord implementa um subconjunto restrito de markdown pensado para chat e deixa de fora tabelas, notas de rodapé, listas de tarefas e listas de definições. O seu subconjunto cobre negrito, itálico, rasurado, cabeçalhos e blocos de código delimitados. Conteúdo destinado ao Discord deve ficar dentro desses 5 elementos.

Como testo a sintaxe estendida antes de publicar?

Cole o elemento na pré-visualização em tempo real do editor online, que apresenta GFM mais notas de rodapé em menos de 1 segundo. Para qualquer outro destino, cole um exemplo de 2 linhas na própria app de destino; a matriz de suporte cobre os 4 casos mais comuns.