Guia de Markdown para Escritores e Desenvolvedores
Domine a sintaxe Markdown do básico ao avançado — tabelas, blocos de código, listas de tarefas e as diferenças entre os sabores do Markdown.
Markdown é o formato de escrita mais próximo de um padrão universal na internet. Ele é usado em READMEs do GitHub, documentos do Notion, mensagens do Slack, sites de documentação, posts de blog e anotações de desenvolvedores. Aprenda uma vez e você o usará em todo lugar — pelo resto da sua carreira.
O que é Markdown?
Markdown é uma linguagem de marcação leve criada por John Gruber em 2004. A ideia central: escrever em texto simples usando convenções de pontuação básicas, que são renderizadas como HTML formatado e elegante.
Este **texto em negrito** e *texto em itálico* são renderizados instantaneamente.
Renderizado como: Este texto em negrito e texto em itálico são renderizados instantaneamente.
O texto bruto ainda é perfeitamente legível — mesmo antes de ser renderizado.
Sintaxe básica
Títulos
# Título 1
## Título 2
### Título 3
#### Título 4
Use títulos para criar uma hierarquia no documento. # H1 é normalmente o título da página — use apenas um por documento.
Ênfase
**texto em negrito**
*texto em itálico*
***negrito e itálico***
~~tachado~~
Listas
Lista não ordenada:
- Item um
- Item dois
- Item aninhado (recue com 2 espaços)
- Outro item aninhado
- Item três
Lista ordenada:
1. Primeiro passo
2. Segundo passo
3. Terceiro passo
Links e imagens
[Texto do link](https://example.com)
[Link com título](https://example.com "Tooltip ao passar o mouse")
Citações em bloco
> Isto é uma citação em bloco.
> Ela pode ocupar várias linhas.
> Você pode aninhar citações:
> > Assim.
Linha horizontal
---
(Três ou mais traços, asteriscos ou underscores em uma linha própria)
Blocos de código
Código inline usa crases simples:
Use a função `console.log()` para depuração.
Blocos de código cercados usam três crases com um identificador de linguagem opcional para destaque de sintaxe:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
As linguagens suportadas incluem javascript, typescript, python, bash, sql, json, yaml, css, html, go, rust e dezenas de outras — dependendo do renderizador.
Tabelas
Tabelas em Markdown usam caracteres de barra vertical e traços:
| Coluna 1 | Coluna 2 | Coluna 3 |
|----------|----------|----------|
| Célula A | Célula B | Célula C |
| Célula D | Célula E | Célula F |
Alinhe colunas com dois-pontos na linha separadora:
| Esquerda | Centro | Direita |
|:---------|:------:|--------:|
| E | C | D |
Tabelas fazem parte do GitHub Flavored Markdown (GFM), não do Markdown padrão. Funcionam no GitHub, VS Code, na maioria das plataformas de documentação e no MDX.
Listas de tarefas (GFM)
- [x] Escrever a introdução
- [x] Adicionar exemplos de código
- [ ] Revisar e publicar
- [ ] Adicionar imagens
Renderizado como checkboxes interativos no GitHub. Amplamente suportado nos renderizadores de Markdown modernos.
Sabores de Markdown
O Markdown original é intencionalmente minimalista. Diversas extensões surgiram ao longo do tempo:
| Sabor | Usado em | Principais adições |
|---|---|---|
| CommonMark | Diversas plataformas | Especificação padronizada |
| GitHub Flavored (GFM) | GitHub, GitLab | Tabelas, listas de tarefas, tachado, autolinks |
| MDX | Sites React | Componentes JSX dentro do Markdown |
| Pandoc Markdown | Documentos acadêmicos | Notas de rodapé, citações, matemática |
| MultiMarkdown | Ferramentas macOS | Tabelas, metadados, notas de rodapé |
Na dúvida, use GFM — é o sabor estendido com maior suporte.
Front matter
Muitos processadores de Markdown suportam front matter YAML no topo de um arquivo para metadados:
---
title: "Título do Meu Artigo"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---
# O conteúdo do artigo começa aqui
O front matter é analisado separadamente do corpo do documento e usado para coisas como títulos de página, datas e metadados de SEO.
MDX: Markdown + JSX
MDX é um Markdown que pode conter componentes React. É ideal para documentação e posts de blog em sites baseados em React (Next.js, Gatsby, Astro):
import { Alert } from '../components/Alert'
## Nota importante
<Alert type="warning">
Este recurso está obsoleto na v3.
</Alert>
O conteúdo **Markdown** regular continua abaixo.
Isso combina a simplicidade do Markdown com o poder de componentes interativos.
Escapando caracteres especiais
Prefixe caracteres especiais do Markdown com uma barra invertida para renderizá-los literalmente:
\*não itálico\*
\# não é um título
\[não é um link\]
Dicas para documentos Markdown melhores
- Uma frase por linha — Deixa os diffs mais limpos no Git; renderiza de forma idêntica, pois o Markdown ignora quebras de linha simples.
- Linha em branco entre blocos — Sempre deixe uma linha em branco entre parágrafos, títulos, listas e blocos de código.
- Marcadores de lista consistentes — Escolha
-ou*para listas não ordenadas e mantenha o mesmo padrão em todo o projeto. - Links de referência para URLs repetidas — Defina uma vez, use várias vezes:
Veja a [documentação][docs] e o [changelog][docs]. [docs]: https://example.com/docs - Texto alternativo para toda imagem — Essencial para acessibilidade e SEO.
Verificando a legibilidade
Markdown facilita a escrita — mas escrever com facilidade pode produzir textos difíceis de ler. Use nossa ferramenta Readability Score para verificar o nível de leitura Flesch-Kincaid, a complexidade das frases e o uso de voz passiva. Busque uma linguagem clara e concisa no nível de leitura entre a 8ª e a 10ª série para públicos gerais.
Markdown é uma daquelas ferramentas que se aprende em 10 minutos e traz benefícios para a vida toda. Comece a escrever com ele hoje — seus futuros colaboradores (e seu eu do futuro) vão agradecer.