Guia de Sintaxe Markdown — Cabeçalhos, Tabelas, Código e Mais

Esta é a referência de sintaxe Markdown que você pode favoritar e revisitar. Cada elemento coberto com um exemplo real — títulos, ênfase, links, imagens, listas, blocos de código, tabelas, citações em bloco e mais. Onde um recurso faz parte do CommonMark padrão, está marcado como tal; extensões do GitHub Flavored Markdown (GFM) são explicitamente identificadas para que você saiba o que é universalmente suportado e o que depende do renderizador.

Títulos

Markdown tem dois estilos de título. O estilo ATX usa caracteres de hash — um # para h1 até seis ###### para h6. O estilo setext usa sublinhados de caracteres = ou - e só chega a h1 e h2. ATX é o estilo que você deve usar em todos os lugares — é explícito, escala para todos os seis níveis e é o que toda ferramenta suporta. Um erro comum: esquecer o espaço após o #. Estritamente falando, #Título não é um título no CommonMark — o espaço é obrigatório.

# Page Title (h1)
## Section Heading (h2)
### Subsection (h3)
#### Detail Level (h4)
##### Minor Heading (h5)
###### Smallest Heading (h6)

---

<!-- Setext style — only h1 and h2, rarely used -->
Page Title
==========

Section Heading
---------------

Em um documento real, você normalmente usa um h1 no topo (o título do documento), h2 para seções principais e h3 para subseções dentro delas. Ir mais fundo que h3 é um sinal de que seu documento pode precisar de reestruturação em vez de outro nível de aninhamento.

Formatação de Texto

Negrito usa asteriscos duplos ou sublinhados duplos. Itálico usa asteriscos simples ou sublinhados simples. Negrito-itálico combina três de qualquer um. Tachado é uma extensão GFM e usa til duplo. Código inline usa backticks.

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___
~~Strikethrough~~ (GFM only)
`inline code`

As variantes * e _ são principalmente intercambiáveis, mas diferem em um caso extremo: ênfase no meio de palavras. Asteriscos funcionam no meio de palavras (in*crível*mente renderiza como incrívelmente), mas sublinhados não — in_crível_mente renderiza literalmente no CommonMark porque sublinhados dentro de palavras são tratados como caracteres de palavra, não marcadores de ênfase. Isso importa na escrita técnica onde sublinhados aparecem em identificadores. Como regra: use * para ênfase e reserve _ apenas se você tiver uma forte preferência de estilo. Não misture * e _ dentro do mesmo span de ênfase — *texto_ não fechará corretamente.

Links e Imagens

Há três estilos de link: links inline, links de referência e autolinks. Imagens seguem a mesma sintaxe dos links inline mas com um prefixo !.

<!-- Inline link: [text](url) or [text](url "title") -->
Read the [CommonMark spec](https://spec.commonmark.org/current/ "CommonMark Specification")
Format Markdown with the [Markdown Formatter](/markdown-formatter)

<!-- Reference link: define the URL separately — cleaner in long documents -->
Check the [GFM spec][gfm] for GitHub-specific extensions.

[gfm]: https://github.github.com/gfm/

<!-- Autolink: angle brackets make a URL or email clickable -->
<https://commonmark.org>
<[email protected]>

<!-- Image: same as inline link but with ! prefix -->
![Project screenshot](./docs/screenshot.png "Dashboard view")
![Alt text for accessibility](https://example.com/logo.png)

Listas

Listas não ordenadas usam -, * ou + como marcadores de bala. Listas ordenadas usam números seguidos de ponto. Aninhe listas indentando dois ou quatro espaços. Listas de tarefas (GFM) usam [ ] para itens não marcados e [x] para itens marcados.

<!-- Unordered list -->
- Install dependencies
- Configure environment variables
- Run the dev server

<!-- Ordered list -->
1. Clone the repository
2. Run `npm install`
3. Copy `.env.example` to `.env` and fill in values
4. Run `npm run dev`

<!-- Nested list (indent 2 or 4 spaces) -->
- Backend
  - Set up PostgreSQL
  - Configure connection string
- Frontend
  - Install Tailwind
  - Configure PostCSS

<!-- Task list (GFM) — great for README checklists -->
## Release Checklist

- [x] Unit tests passing
- [x] End-to-end tests passing
- [ ] Changelog updated
- [ ] Docker image tagged
- [ ] Deployment approved

Código — Inline e Cercado

Código inline usa um único backtick em cada lado. Para blocos, use três backticks (blocos de código cercados) e opcionalmente especifique o identificador de linguagem logo após a cerca de abertura — isso habilita o realce de sintaxe no GitHub, pré-visualizações do VS Code e na maioria dos geradores de site estático. Você também pode usar blocos de código indentados (4 espaços de indentação), mas prefira blocos cercados: eles suportam dicas de linguagem, são explícitos e funcionam mesmo quando o conteúdo circundante também tem indentação.

<!-- Inline code -->
Use the `fetch()` API to make HTTP requests.
Set the `Content-Type` header to `application/json`.

<!-- Fenced code block with language hint -->
```python
import json

with open("config.json") as f:
    config = json.load(f)

print(config["database"]["host"])
```

```typescript
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}
```

```bash
# Install dependencies and start the dev server
npm install
npm run dev
```

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build"
  }
}
```

```yaml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
```

Identificadores de linguagem comuns: python, js ou javascript, ts ou typescript, bash ou sh, json, yaml, html, css, sql, go, rust, java. Pré-visualize como seu Markdown renderiza usando a ferramenta Pré-visualização de Markdown.

Tabelas (GFM)

Tabelas são uma extensão do GitHub Flavored Markdown — elas não fazem parte do padrão CommonMark. Funcionam no GitHub, GitLab, na maioria dos geradores de site estático e VS Code, mas não em todos os processadores Markdown. A sintaxe usa caracteres pipe para separar colunas e uma linha separadora de traços para marcar o cabeçalho. Dois pontos na linha separadora controlam o alinhamento das colunas.

| Feature              | CommonMark | GFM       |
| -------------------- | :--------: | :-------: |
| Headings             | ✅         | ✅        |
| Bold / Italic        | ✅         | ✅        |
| Fenced code blocks   | ✅         | ✅        |
| Tables               | ❌         | ✅        |
| Task lists           | ❌         | ✅        |
| Strikethrough        | ❌         | ✅        |
| Autolinks            | ✅         | ✅ (ext.) |

O alinhamento de coluna é definido na linha separadora. :--- alinha à esquerda (o padrão). ---: alinha à direita. :---: centraliza. Você não precisa preencher colunas com espaços para alinhá-las visualmente na fonte — isso é cosmético e não tem efeito na saída renderizada. Os pipes no início e no final de cada linha são tecnicamente opcionais no GFM, mas incluí-los é o estilo mais claro.

Citações em Bloco

Citações em bloco prefixam cada linha com >. Citações aninhadas usam >>. Você pode incluir outros elementos Markdown — títulos, listas, blocos de código — dentro de uma citação em bloco, o que os torna úteis para caixas de destaque em documentação.

> **Note:** As of Node.js 18, the `fetch` API is available globally
> without importing anything. No more `node-fetch` dependency.

> This is a quote that spans
> multiple lines.
>
> And has a second paragraph.

> Outer quote.
>
> > Nested quote — useful for "quoting a quote" in changelogs
> > or spec discussions.

<!-- Blockquote containing a code block — useful for quoting error messages -->
> The migration failed with:
>
> ```
> ERROR: relation "users" already exists
> ```

Regras Horizontais, Quebras de Linha e Escape

Esses três recursos confundem as pessoas porque seu comportamento parece um bug até que você conhece as regras. Regras horizontais, quebras de linha forçadas e escape com barra invertida têm todos uma sintaxe específica que não é óbvia.

<!-- Horizontal rules: three or more of ---, ***, or ___ on their own line -->
---
***
___

<!-- All three render as <hr>. Most common style is --- -->

<!-- Hard line breaks: end a line with two trailing spaces, or use backslash -->
First line with two trailing spaces
Second line (rendered as a new line, not a new paragraph)

First line with backslash\
Second line (same result)

<!-- A single newline in Markdown source is NOT a line break — it's a space.
     Two newlines = a paragraph break. -->

<!-- Backslash escaping: put  before any Markdown character to render it literally -->
*This is not italic*
# This is not a heading
[Not a link](not-a-url)
`Not inline code`

<!-- Characters that can be escaped -->
\ ` * _ { } [ ] ( ) # + - . !

HTML no Markdown

A maioria dos processadores Markdown passa HTML bruto inalterado, o que desbloqueia alguns padrões úteis que a sintaxe Markdown pura não pode expressar. O caso de uso mais comum em READMEs do GitHub é a seção recolhível <details>/<summary>. Outros úteis: <kbd> para atalhos de teclado, e atributos id personalizados em títulos para links de âncora precisos.

<!-- Collapsible section — very common in GitHub READMEs -->
<details>
<summary>Click to expand: Advanced configuration options</summary>

You can override the defaults by creating a `config.local.json` file
in the project root. Supported keys:

| Key        | Default | Description             |
| ---------- | ------- | ----------------------- |
| `port`     | 3000    | Dev server port         |
| `logLevel` | `info`  | One of debug/info/warn  |

</details>

<!-- Keyboard shortcuts -->
Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the command palette.

<!-- Custom heading ID for anchor links -->
<h2 id="configuration-reference">Configuration Reference</h2>

<!-- Link to that heading from anywhere -->
See the [Configuration Reference](#configuration-reference).

Uma ressalva importante: o bloco <details> requer uma linha em branco entre a tag de fechamento </summary> e o conteúdo do corpo se esse conteúdo contiver Markdown. Sem a linha em branco, o Markdown dentro não será analisado — renderizará como texto bruto. Você pode limpar e formatar seus arquivos Markdown com a ferramenta Formatador de Markdown.

Conclusão

Isso cobre a sintaxe completa — CommonMark padrão e as extensões GFM que os desenvolvedores usam diariamente. Para a palavra autoritativa sobre casos extremos, a especificação CommonMark e a especificação GFM são ambas documentos legíveis, não apenas dumps de referência. A referência rápida CommonMark é um resumo prático de página única. As páginas de sintaxe básica do Guia de Markdown e sintaxe estendida também são bem organizadas se você quiser mais explicação em prosa junto com exemplos. Quando você precisa ver exatamente como seu Markdown ficará antes de confirmar, a ferramenta Pré-visualização de Markdown o renderiza ao vivo no seu navegador. Para limpar formatação inconsistente em um documento, o Formatador de Markdown normaliza estilos de título, marcadores de lista e espaçamento. E para produzir HTML limpo da saída Markdown, o Formatador HTML embeleza o que o processador Markdown emite.