A maioria dos documentos começa como um arquivo de texto simples com alguns asteriscos e cerquilhas. Esse arquivo geralmente é Markdown. Não é a única forma de escrever para a web, mas é o formato padrão para READMEs, rastreadores de issues, chatbots e sites estáticos, porque a fonte pode ser lida antes de ser renderizada.
Este artigo é um tutorial rápido e prático. Ele assume que você tem dez minutos e um editor de texto. Nenhuma instalação é necessária.
O que é Markdown
Markdown é uma sintaxe de marcação leve. John Gruber publicou a especificação original em 2004 com um objetivo: um formato que ficasse bem em texto simples e se convertesse limpamente para HTML. Desde então, tornou-se o formato de entrada do GitHub, Obsidian, Notion, muitos geradores de sites estáticos e a maioria das saídas de grandes modelos de linguagem.
A ideia central é simples. Você marca a estrutura com pontuação em vez de tags:
# Este é um título
Este é um parágrafo.
- Este é um item de lista
- Este é outro item
Um analisador converte isso em HTML. Diferentes analisadores suportam diferentes extensões, e é aí que entram os padrões.
Os padrões Markdown importam
Markdown não tem um único padrão oficial. A especificação original de Gruber deixa lacunas que diferentes ferramentas preencheram de formas incompatíveis. Se você escreve uma tabela em um aplicativo e cola em outro, ela pode quebrar. Você precisa saber qual dialeto está usando.
- CommonMark. Uma especificação rigorosa e bem testada iniciada em 2014. Define a sintaxe principal com precisão. Se você quer portabilidade, escreva CommonMark.
- GitHub Flavored Markdown (GFM). Adiciona tabelas, listas de tarefas, tachados, blocos de código cercados e autolinks. É o que você vê em READMEs e comentários de issues do GitHub.
- Pandoc Markdown. Adiciona citações, notas de rodapé, listas de definições, subscritos, sobrescritos e matemática. Comum na escrita acadêmica.
- Obsidian / Quarto / MDX. Adicionam wikilinks, destaques, células de código executáveis ou componentes incorporados. São poderosos, mas pouco portáteis.
Para o trabalho diário, GFM é o alvo mais seguro. Para documentos longos que possam se mover entre ferramentas, CommonMark mais um conjunto documentado de extensões é melhor.
Noções básicas de Markdown
Títulos
Use de um a seis cerquilhas. Uma é a maior.
# Título 1
## Título 2
### Título 3
Parágrafos e quebras de linha
Separe parágrafos com uma linha em branco. Termine uma linha com dois espaços ou uma barra invertida para forçar uma quebra de linha.
Este é o primeiro parágrafo.
Este é o segundo.
Ênfase
_itálico_ ou _itálico_
**negrito** ou **negrito**
**_negrito e itálico_**
~~tachado~~ (somente GFM)
Listas
Listas não ordenadas usam -, * ou +:
- Item um
- Item dois
- Item aninhado
Listas ordenadas usam números:
1. Passo um
2. Passo dois
3. Passo três
Os números não precisam estar corretos. Markdown os renumera ao renderizar. Ainda assim, use números sequenciais para que a fonte fique legível.
Links e imagens
[Texto do link](https://example.com)
[Link com título](https://example.com "Título")
Para links internos, use caminhos relativos:
[Converter Markdown para PDF](/tools/markdown-to-pdf)
Código
Código inline usa backticks simples: `console.log("hi")`.
Blocos de código usam três backticks:
```python
def hello():
return "hello"
```
Adicione um identificador de linguagem após os backticks de abertura para que o destaque de sintaxe funcione.
## Truques comuns e exemplos
### Citações
```markdown
> Esta é uma citação.
> Ela pode se estender por várias linhas.
Você pode aninhá-las:
> Citação externa
>
> > Citação aninhada
Linhas horizontais
---
Use três ou mais hifens, asteriscos ou sublinhados sozinhos em uma linha.
Listas de tarefas
O GFM suporta caixas de seleção:
- [x] Escrever o rascunho
- [ ] Revisar as tabelas
- [ ] Publicar o artigo
Elas são renderizadas como caixas de seleção desabilitadas no HTML. Não as use como substituto para entradas reais de formulário.
Escapar caracteres
Prefixe caracteres Markdown com uma barra invertida quando quiser que apareçam literalmente:
\*não itálico\*
\# não é um título
Truques avançados e exemplos
Tabelas
Tabelas são uma extensão do GFM, não parte da especificação original do Markdown.
| Recurso | CommonMark | GFM |
| ----------------- | ---------- | --- |
| Tabelas | Não | Sim |
| Listas de tarefas | Não | Sim |
O alinhamento é opcional:
| Esquerda | Centro | Direita |
| :------- | :----: | ------: |
| A | B | C |
Mantenha as tabelas simples. Tabelas aninhadas, mesclagem de linhas e colunas não são padrão e frequentemente falham.
Notas de rodapé
Pandoc e alguns analisadores GFM suportam notas de rodapé:
Aqui está uma afirmação.[^1]
[^1]: Este é o texto da nota de rodapé.
Se você precisar de notas de rodapé em um PDF renderizado, use um conversor que suporte a sintaxe Pandoc ou insira-as manualmente.
Matemática
Pandoc e muitos editores modernos suportam matemática LaTeX:
Matemática inline: $E = mc^2$
Matemática em bloco:
$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$
A renderização matemática depende do analisador e do formato de saída. HTML geralmente precisa de MathJax ou KaTeX. Conversores para PDF frequentemente precisam de um backend LaTeX.
Listas de definições
Outra extensão do Pandoc:
Termo
: Definição do termo.
Outro termo
: Outra definição.
HTML dentro do Markdown
Quando o Markdown não é suficiente, você pode recorrer ao HTML:
<p style="color: red;">Este texto é vermelho.</p>
Isso funciona para layout, vídeos incorporados ou atributos que o Markdown não suporta. Mas reduz a portabilidade, então use com moderação.
Quando converter Markdown
Markdown é ótimo para escrever e controle de versão. É ruim para documentos finais que precisam parecer idênticos em qualquer lugar. Por isso existem conversores.
Se você tem um rascunho Markdown que precisa se tornar um PDF compartilhável, use o conversor de Markdown para PDF. Ele roda no navegador, então seu arquivo nunca sai da sua máquina.
Se você parte de um PDF e quer Markdown editável, use o conversor de PDF para Markdown. Ele extrai títulos, listas e parágrafos sem enviar nada para um servidor.
Cheatsheet de Markdown
| Elemento | Sintaxe | Saída de exemplo |
|---|---|---|
| Título 1 | # H1 | H1 |
| Título 2 | ## H2 | H2 |
| Título 3 | ### H3 | H3 |
| Negrito | **bold** | bold |
| Itálico | *italic* | italic |
| Tachado | ~~text~~ | |
| Código inline | `code` | code |
| Link | [text](url) | text |
| Imagem |  | imagem |
| Citação | > quote | citação |
| Lista não ordenada | - item | item de lista |
| Lista ordenada | 1. item | item de lista |
| Linha horizontal | --- | linha horizontal |
| Bloco de código | ```lang | bloco com destaque |
| Lista de tarefas | - [ ] task | caixa de seleção |
| Tabela | | a | b | | tabela |
Imprima esta tabela, cole-a perto do monitor e raramente precisará consultar a sintaxe do Markdown novamente.
Considerações finais
Markdown recompensa a moderação. Use a sintaxe principal para 90% do que escreve. Recorra a tabelas, notas de rodapé e HTML apenas quando o documento realmente precisar. Se você se ater ao CommonMark ou GFM, seus arquivos se moverão entre editores, plataformas e conversores sem surpresas.
