Folha de Referência Markdown: 21 elementos de sintaxe numa página
Uma folha de referência markdown é uma página única que associa cada elemento markdown à respetiva sintaxe exata, para que possa formatar um documento sem recorrer à documentação completa. Esta página cobre os 21 elementos da sintaxe markdown em duas tabelas: os 10 elementos básicos que John Gruber definiu na especificação original de 2004 e os 11 elementos alargados que variantes posteriores, como o CommonMark (2014) e o GitHub Flavored Markdown (2017), acrescentaram depois. Todos os exemplos de sintaxe desta página funcionam também no editor markdown online, onde a pré-visualização em tempo real mostra o resultado renderizado no ecrã à medida que escreve.
Sintaxe básica
A sintaxe básica cobre os 10 elementos do desenho original do markdown de 2004, e todas as aplicações markdown renderizam estes elementos de forma idêntica. Estes 10 elementos resolvem a maior parte da escrita do dia a dia: a estrutura vem dos títulos e das listas, o destaque vem do negrito e do itálico, e as referências vêm das ligações e das imagens. Se um documento usar apenas as linhas desta tabela, é renderizado corretamente no GitHub, no Obsidian, no Reddit, no Discord e em qualquer editor criado depois de 2004.
| Elemento | Syntax | Resultado renderizado |
|---|---|---|
| Título | # H1 / ## H2 / ### H3 | Títulos de secção dos níveis 1 a 6; um # por nível |
| Negrito | **strong words** | palavras em negrito |
| Itálico | *slanted words* | palavras em itálico |
| Citação | > quoted line | Bloco de citação indentado com uma margem à esquerda |
| Lista ordenada | 1. Step one 2. Step two | Lista numerada; a numeração é renderizada em sequência |
| Lista não ordenada | - First point - Second point | Lista com marcas; * e + também funcionam como marcadores |
| Código | `inline code` | código inline numa caixa monoespaçada |
| Linha horizontal | --- | Linha divisória a toda a largura entre secções |
| Ligação | [anchor text](https://example.com) | Hiperligação clicável com o rótulo "anchor text" |
| Imagem |  | Imagem incorporada com texto alternativo para acessibilidade |
O marcador de título precisa de um espaço depois do último #, e a linha horizontal precisa de uma linha em branco por cima. Estes dois pormenores causam a maioria das falhas de renderização da sintaxe básica.
Sintaxe alargada
A sintaxe alargada acrescenta 11 elementos que a especificação original de 2004 nunca incluiu, e o suporte depende da variante de markdown que cada aplicação implementa. As tabelas, os blocos de código delimitados e as listas de tarefas chegaram com o GitHub Flavored Markdown, que o GitHub formalizou como especificação em 2017. As notas de rodapé, as listas de definições e o realce vêm de outras variantes e são renderizados em menos aplicações.
| Elemento | Syntax | Resultado renderizado |
|---|---|---|
| Tabela | | Name | Role | | --- | --- | | Ada | Engineer | | Grelha com linha de cabeçalho e colunas alinhadas |
| Bloco de código delimitado | ```json { "id": 1 } ``` | Caixa de código com várias linhas e realce de sintaxe opcional |
| Nota de rodapé | A claim.[^1] [^1]: The source. | Referência numerada com uma nota no fundo da página |
| ID de título | ## Pricing {#pricing} | Título com âncora personalizada para ligações diretas |
| Lista de definições | Term : Meaning of the term | Termo numa linha, definição indentada por baixo |
| Rasurado | ~~old figure~~ | |
| Lista de tarefas | - [x] Ship the draft - [ ] Review edits | Lista de verificação com caixas marcadas e desmarcadas |
| Atalho de emoji | :tada: | O carácter emoji correspondente, 🎉 |
| Realce | ==key phrase== | Frase sobre um fundo colorido |
| Subscrito | H~2~O | H₂O |
| Sobrescrito | x^2^ | x² |
O suporte varia consoante a aplicação: o GitHub renderiza tabelas, blocos de código delimitados, listas de tarefas, rasurado, notas de rodapé e atalhos de emoji, mas ignora realce, subscrito e sobrescrito; o Obsidian suporta tabelas, notas de rodapé, listas de tarefas, rasurado e realce; o Discord aceita negrito, itálico, rasurado e blocos de código, mas não suporta tabelas nem notas de rodapé. Quando a plataforma de destino é desconhecida, os 10 elementos básicos são o conjunto seguro.
Como usar esta folha de referência
Encontre o elemento na coluna da esquerda, copie a sintaxe da coluna do meio e substitua o texto de exemplo pelo seu próprio conteúdo. A coluna do resultado renderizado mostra o aspeto final, para que possa confirmar que o elemento corresponde ao que pretende antes de o copiar. Para qualquer elemento da tabela alargada, verifique primeiro a nota de suporte; uma nota de rodapé que é renderizada no GitHub desaparece no Discord.
A forma mais rápida de verificar a sintaxe markdown é colá-la no editor markdown online. A pré-visualização em tempo real renderiza cada elemento em milissegundos, pelo que uma tabela partida ou um marcador ** por fechar aparece de imediato no ecrã. Os utilizadores que escrevem markdown diariamente tendem a memorizar a tabela básica ao fim de uma semana; a tabela alargada é a parte que vale a pena manter à mão.
Transferir e imprimir
Esta folha de referência cabe numa página A4 e está disponível como ficheiro .md, para que possa guardar uma cópia na sua aplicação de notas ou imprimi-la para a secretária. O ficheiro transferido é, ele próprio, markdown válido, e ambas as tabelas são renderizadas corretamente em qualquer aplicação que suporte tabelas GFM. Abra-o no editor, no Obsidian ou num repositório GitHub e a referência mantém a formatação.
Perguntas frequentes
Qual é a diferença entre sintaxe markdown básica e alargada?
Sintaxe básica designa os 10 elementos da especificação original de 2004, e sintaxe alargada designa os 11 elementos que as variantes posteriores acrescentaram. Todas as aplicações markdown suportam o conjunto básico. O conjunto alargado depende da variante: o CommonMark padronizou o comportamento central em 2014 e o GFM acrescentou tabelas, listas de tarefas e rasurado na sua especificação de 2017.
Todas as aplicações markdown suportam a sintaxe alargada?
Não. O suporte da sintaxe alargada difere de aplicação para aplicação, e nenhuma aplicação renderiza os 11 elementos alargados na totalidade. O GitHub ignora realce e subscrito, o Discord ignora tabelas e notas de rodapé, e o Obsidian cobre a gama mais ampla das três. Os documentos destinados a várias plataformas devem apoiar-se na sintaxe básica mais as tabelas GFM.
É difícil aprender markdown?
Não. O Markdown tem 21 elementos no total, e os 10 elementos básicos cobrem a maioria dos documentos. Um # para títulos, ** para negrito e - para listas representam a maior parte da utilização real. A maioria dos utilizadores escreve markdown com fluência após uma única sessão com um editor com pré-visualização em tempo real, porque a pré-visualização corrige os erros no momento.