Markdown é simples, mas pequenos detalhes mudam o resultado: uma linha em branco, a quantidade de cerquilhas ou a posição de uma barra vertical. Esta página reúne a sintaxe inteira em uma tabela para consulta rápida, e cada tópico tem uma página própria com os casos que costumam dar errado.
Sintaxe completa em uma tela
À esquerda, o que você escreve. À direita, o que o leitor vê. É a mesma renderização que o leitor de Markdown aplica ao seu documento.
| Código Markdown | Resultado renderizado | ||||
|---|---|---|---|---|---|
| # Título 1 ## Título 2 ### Título 3 | Três níveis de título, do maior para o menor. Cada um vira uma entrada do índice automático. | ||||
| **negrito** | negrito | ||||
| *itálico* | itálico | ||||
| ~~riscado~~ | |||||
| - item - outro item |
| ||||
| 1. primeiro 2. segundo |
| ||||
| - [x] feito - [ ] pendente | Lista de tarefas com caixas marcáveis (extensão GFM) | ||||
| [texto](https://exemplo.com) | texto | ||||
|  | Imagem, com a descrição usada como texto alternativo | ||||
| `código` | código | ||||
| ```js const a = 1; ``` | Bloco de código com destaque de sintaxe para a linguagem indicada | ||||
| > citação | citação | ||||
| | A | B | | --- | --- | | 1 | 2 | |
| ||||
| --- | |||||
| Texto[^1] [^1]: A nota. | Nota de rodapé numerada, com link de ida e volta (extensão GFM) |
As quatro regras que mais pegam
Linha em branco separa blocos. Um parágrafo colado no anterior vira o mesmo parágrafo. Uma lista colada no texto acima pode não virar lista. Quando algo não renderiza como esperado, a primeira coisa a checar é se falta uma linha vazia antes.
Quebra de linha simples não quebra a linha. Dentro de um parágrafo, apertar Enter uma vez não produz quebra visível — é preciso deixar dois espaços no fim da linha ou uma linha em branco. Isso surpreende quem vem de um editor de texto comum.
Espaço depois do marcador. #Título não é título; # Título é. O mesmo vale para - item e para 1. item. É o erro mais comum em texto escrito à mão.
Indentação define aninhamento. Dois espaços antes do hífen criam uma sublista; quatro espaços em um contexto errado transformam o texto em bloco de código. Se um trecho apareceu com fonte monoespaçada sem você pedir, quase sempre é indentação sobrando.
CommonMark, GFM e o que muda
Markdown não tem uma especificação única. O CommonMark é a base bem definida — títulos, ênfase, listas, links, citações e código. O GFM (GitHub Flavored Markdown) acrescenta o que a maioria das pessoas considera parte do Markdown, mas não é: tabelas, texto riscado, listas de tarefas, notas de rodapé e detecção automática de links.
Na prática, a dúvida aparece quando um arquivo funciona no GitHub e quebra em outro lugar. A comparação item a item está em GFM e CommonMark. O Sanctuary Reader lê as duas variantes, mais blocos mermaid renderizados como diagrama.
Onde o Markdown é aceito
Saber a sintaxe resolve metade do problema; a outra metade é saber o que cada lugar entende. O mesmo arquivo passa por ferramentas com suportes diferentes, e é aí que o texto quebra.
| Onde | O que esperar |
|---|---|
| GitHub e GitLab | GFM completo: tabelas, tarefas, notas de rodapé e diagramas mermaid no README. |
| Respostas de IA | ChatGPT, Claude e Gemini escrevem em GFM. Fora do chat, os símbolos aparecem crus. |
| Obsidian e apps de notas | CommonMark mais extensões próprias, como links entre notas em colchetes duplos. |
| Slack e Discord | Só um subconjunto: negrito, itálico, código e citação. Títulos e tabelas não valem. |
| Sanctuary Reader | CommonMark, GFM e blocos mermaid, com índice automático a partir dos títulos. |
A regra prática: escreva no subconjunto comum — títulos, ênfase, listas, links, citações e código — e use tabelas e notas de rodapé sabendo que são extensões. Assim o arquivo sobrevive à mudança de ferramenta.
Aprofunde por tópico
- Sintaxe Markdown: guia rápido — títulos, ênfase, listas, links e citações.
- Como fazer tabela em Markdown — resposta direta e exemplos alinhados.
- Como inserir imagem no Markdown — caminho, alt e limitações.
- Bloco de código Markdown — fences e indicação de linguagem.
- GFM e CommonMark — o que é extensão e o que é base comum.
Onde testar o que você escreveu
Consultar a tabela resolve a dúvida de sintaxe; ver o resultado resolve o resto. As páginas de ferramenta abrem com um editor já funcionando: cole o trecho, confira a renderização e siga escrevendo.
- Leitor de Markdown — para documentos longos, com índice e progresso.
- Markdown de IA — para a resposta do ChatGPT ou do Claude cheia de asteriscos.
- Markdown com Mermaid — para diagramas escritos dentro do texto.
- Markdown por URL — para conferir um README antes do commit.