Skip to content

Markdown Folha de referência

Linguagem de marcação leve para texto formatado.

01

Primeiros Passos

Títulos e Parágrafos

Use # para títulos (1 a 6 níveis). A sintaxe alternativa usa === para H1 e --- para H2. Parágrafos precisam de uma linha em branco entre eles. O Markdown foi projetado para ser legível como texto puro.

markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative Heading 1
=====================

Alternative Heading 2
---------------------

This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.

Quebras de Linha

Dois espaços no fim da linha ou uma barra invertida criam uma quebra de linha dura (<br>). Sem eles, uma quebra de linha única é uma quebra suave que se junta num parágrafo. Sempre deixe uma linha em branco para separar parágrafos.

markdown
First line  
Second line (two trailing spaces above)

Or use a backslash at end of line\
to force a line break.

Soft wrap without break:
just continue on the next line
and it joins into one.

Comentários

O Markdown não tem sintaxe oficial de comentário, mas comentários HTML (<!-- -->) funcionam na maioria dos renderizadores e ficam ocultos na saída. O truque [//]: # usa uma referência de link vazia para adicionar notas. Comentários continuam visíveis no código-fonte.

markdown
<!-- HTML comments work in most Markdown -->

[//]: # (This is a comment)

[//]: # "Another comment style"

<!-- 
  Multi-line comment
  not rendered in output
-->

Espaços em Branco e Indentação

Quatro espaços no início transformam texto em bloco de código — cuidado com indentação acidental. A indentação importa em listas aninhadas (2 a 4 espaços por nível). Tabs geralmente são tratados como 4 espaços. Use espaços de forma consistente para evitar problemas de renderização entre parsers.

markdown
Paragraph one.

    This is an indented code block
    because of 4 spaces.

> Quoted text needs > prefix.

   Three spaces is just text
   (less than 4).

Linhas Horizontais

Três ou mais hífens, asteriscos ou underscores criam uma linha horizontal (<hr>). Hífens são os mais comuns. Espaços entre os caracteres são permitidos. Por clareza, deixe linhas em branco ao redor das linhas horizontais. Evite confundir --- (linha) com # (título).

markdown
---

***

___

   * * *

Text above

---

Text below
02

Formatação de Texto

Negrito e Strong

Asteriscos ou underscores duplos produzem negrito (<strong>). Asteriscos são preferidos porque underscores não funcionam no meio de palavras (snake_case). Você pode aninhar outros destaques dentro do negrito. Tags HTML <strong> funcionam como alternativa.

markdown
**bold text**
__also bold__

**bold with *italic* inside**

<strong>HTML bold also works</strong>

**bold**

Itálico e Ênfase

Asteriscos ou underscores simples criam itálico (<em>). Asteriscos funcionam no meio de palavras; underscores tratam underscores internos como literais (então no_italic_here não vira itálico). Use <em> como alternativa. Itálico serve para ênfase, não apenas estilo.

markdown
*italic text*
_also italic_

*italic*

<em>HTML italic</em>

normal *italic* normal

Negrito + Itálico Combinados

Asteriscos/underscores triplos produzem negrito e itálico ao mesmo tempo. Você também pode aninhá-los: negrito contendo itálico ou vice-versa. A ordem não importa para a renderização, mas deve ser consistente para facilitar a leitura.

markdown
***bold and italic***
___also both___

**_bold and italic_**
*__bold and italic__*

combine **bold** and *italic*

Riscado

Tis duplos (~~) criam texto riscado, parte do GitHub Flavored Markdown e hoje amplamente suportado. As tags HTML <del> e <s> são equivalentes. O Markdown padrão (original) não inclui riscado.

markdown
~~strikethrough~~

~~crossed out text~~

<del>HTML delete</del>
<s>HTML strikethrough</s>

~~done~~ and ~~pending~~

Marcação / Realce

Igualdades duplas (==) para realce são uma extensão suportada por alguns parsers (não faz parte do núcleo do GFM). A tag HTML <mark> funciona universalmente. Use realce com moderação para chamar atenção a termos-chave — o excesso reduz o efeito.

markdown
==highlighted text==

<mark>HTML mark</mark>

This is ==important== text.

Compare **bold**, *italic*, ==mark==.

Subscrito e Sobrescrito

A sintaxe de til (subscrito) e circunflexo (sobrescrito) (~ ~ e ^ ^) são extensões fora do Markdown padrão e do GFM — suportadas por Pandoc, R Markdown e alguns outros. Para suporte universal, use HTML <sub> e <sup> ou caracteres Unicode.

markdown
H~2~O is water

E = mc^2^

x^2^ + y^2^ = r^2^

1st^st^ January

CO~2~ emissions
03

Listas

Listas Não Ordenadas

Use -, * ou + para itens de lista não ordenada — escolha um e seja consistente (- é o mais comum). Indente 2 a 4 espaços para itens aninhados. Misturar marcadores na mesma lista pode causar problemas em alguns parsers. Um item por linha.

markdown
- item one
- item two
- item three

* asterisk works too
+ plus sign also works

  - sub-item (indent 2 spaces)
  - another sub-item

Listas Ordenadas

Listas ordenadas usam números seguidos de ponto. Os números não precisam ser sequenciais — o Markdown os renumera. Para começar em um número específico, use-o primeiro (10. começa em 10). Use 1. em cada um dos itens para numeração automática.

markdown
1. first
2. second
3. third

1. auto-numbered
1. still increments
1. third item

10. starts at 10
11. next

Listas Aninhadas

Indente itens de listas aninhadas com 2 a 4 espaços (4 é o mais seguro para tipos mistos). Você pode misturar listas ordenadas e não ordenadas em níveis diferentes. Aninhamento profundo (3+ níveis) prejudica a leitura — considere reestruturar. Mantenha a indentação consistente.

markdown
1. top level
   - nested unordered
   - second nested
2. back to top
   1. nested ordered
   2. another
3. third top

- fruits
  - apple
    - granny smith
  - banana

Listas de Tarefas

A sintaxe de lista de tarefas (- [x] e - [ ]) é uma extensão do GitHub Flavored Markdown. O checkbox é renderizado como interativo no GitHub/GitLab. Funciona com listas ordenadas e não ordenadas. Ótimo para READMEs, issues e acompanhamento de progresso.

markdown
- [x] completed task
- [ ] incomplete task
- [ ] another todo

1. [x] done
2. [ ] not done

- [x] Write the docs
- [ ] Review PR
- [ ] Deploy

Listas Frouxas vs Compactas

Se os itens da lista forem separados por linhas em branco, a lista é 'frouxa' (cada item envolvido em <p>). Sem linhas em branco, é 'compacta' (sem wrappers <p>). Isso afeta o espaçamento na saída HTML. Adicione linhas em branco deliberadamente para controlar o empacotamento de parágrafos.

markdown
- tight item
- tight item
- tight item

- loose item

- loose item

- loose item

Lista com Múltiplos Parágrafos

Para incluir múltiplos parágrafos ou elementos de bloco num item de lista, indente a continuação com 4 espaços (ou alinhe com o conteúdo do marcador da lista). Linhas em branco separam os sub-blocos. Isso é essencial para estruturas de lista complexas, mas fácil de errar.

markdown
- First item

  Second paragraph of first item.

- Second item

  > A blockquote inside a list item.
  >
  > Must be indented to align.

- Third item
05

Imagens

Imagem Básica

A sintaxe de imagem é como a de links, mas com prefixo !. O texto alternativo (alt) é obrigatório para acessibilidade — ele descreve a imagem para leitores de tela e aparece se a imagem não carregar. O caminho pode ser relativo, absoluto ou uma URL. O título é opcional.

markdown
![alt text](image.png)

![alt text](https://example.com/img.png)

![alt text](/path/to/image.png "Optional title")

Imagem com Texto Alternativo

O texto alternativo deve ser significativo e conciso — descreva o propósito da imagem, não apenas 'imagem'. Para imagens decorativas, um alt vazio (alt='') é aceitável para dizer aos leitores de tela que a ignorem. Nunca use 'imagem de' ou 'foto de' — leitores de tela já anunciam isso.

markdown
![A diagram showing the system architecture](architecture.png)

![Photo: mountain landscape at sunset](mountains.jpg "Sunset over the Alps")

![](decorative-icon.png)

Imagens com Link

Envolva uma imagem num link aninhando a sintaxe de imagem dentro da sintaxe de link: [![alt](img)](url). Comum em miniaturas que apontam para versões em tamanho grande, badges que apontam para o status de CI e logos que apontam para a home. Mantenha o alt descrevendo o destino, não apenas a imagem.

markdown
[![alt text](thumbnail.png)](https://example.com/full)

[![logo](logo.png "Visit home")](/)

[![badge](https://img.shields.io/build.svg)](https://ci.example.com)

Imagens por Referência

Imagens por referência usam o mesmo estilo de referência dos links, com prefixo !. Defina a referência da imagem uma vez e reutilize. Útil quando a mesma imagem aparece várias vezes ou para manter parágrafos cheios de imagens legíveis.

markdown
![alt text][img-ref]

[img-ref]: https://example.com/image.png "Title"

![alt][logo]

[logo]: /assets/logo.png

Dimensões de Imagem e Figure

O Markdown padrão não tem sintaxe de dimensionamento de imagem — use HTML <img> com atributos width/height. Larguras em porcentagem permitem dimensionamento responsivo. A combinação <figure> + <figcaption> fornece legendas semânticas (HTML5). Alguns Markdowns estendidos (Pandoc) suportam ![alt](img){width=300}.

markdown
<img src="image.png" width="300" height="200" alt="sized image">

<img src="banner.png" width="100%" alt="responsive">

<figure>
  <img src="diagram.png" alt="flowchart">
  <figcaption>Figure 1: System flow</figcaption>
</figure>
06

Código Inline e Escape

Código Inline

Envolva código inline em crases simples. Para mostrar crases dentro do código, use crases duplas como delimitador (ou mais). Código inline é renderizado em monoespaçada e não é analisado como Markdown. Ótimo para nomes de arquivos, comandos e identificadores de código.

markdown
Use the `printf()` function.

Inline code: `const x = 42;`

Code with backticks: ``use `code` here``

A `<div>` element.

Escapando Crases em Spans de Código

Para incluir uma crase dentro de um code span, use mais crases como delimitador do que aparecem dentro: crases duplas em torno de uma crase simples. Fora de code spans, escape a crase com barra invertida. O fechamento deve ter o mesmo comprimento da abertura.

markdown
To show a backtick inside code,
use more backticks as delimiters:

`` ` ``        one backtick
`` a`b ``      backtick inside text

Use \ to escape outside code:
A literal backtick: \`

Code Spans e Espaços em Branco

Code spans preservam exatamente os espaços internos. Um truque comum: envolva o conteúdo com um espaço único no início/fim para exibir espaços nas bordas que, de outro modo, seriam removidos. Um espaço de cada lado é removido automaticamente.

markdown
`  spaced  `  (spaces preserved)

` code ` with one space pad

`function f() { return; }`

`  multi   word   code  `

Escapes com Barra Invertida

A barra invertida escapa caracteres especiais do Markdown: crase, asterisco, underscore, chaves, colchetes, parênteses, hash, mais, menos, ponto, exclamação e a própria barra invertida. Escapar renderiza o caractere literalmente. Só escape caracteres que, de outro modo, seriam interpretados como formatação.

markdown
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an image

Caracteres a Escapar

Estes são os caracteres escapáveis do Markdown. O escape nem sempre é necessário em qualquer lugar — # só importa no início da linha, - em contexto de lista, e assim por diante. Na dúvida, escape. Chaves e parênteses geralmente só precisam de escape em contextos específicos (links, template strings).

markdown
\\     backslash
\`     backtick
\*     asterisk
\_     underscore
\{ \}  curly braces
\[ \]  square brackets
\( \)  parentheses
\#     hash
\+     plus
\-     minus
\.     dot
\!     exclamation
07

Blocos de Código

Blocos de Código Indentados

Indentar com 4 espaços (ou um tab) cria um bloco de código. Blocos indentados não têm realce de sintaxe nem tag de linguagem. Não podem ser usados dentro de itens de lista (são tratados como continuação). Prefira blocos de código cerca (fenced) em conteúdo novo — blocos indentados são legado.

markdown
Normal paragraph.

    // indented code (4 spaces)
    function hello() {
      console.log("hi");
    }

Back to normal text.

Blocos de Código Cerca (Fenced)

Três crases ou três tis criam blocos de código cerca. Cercas são preferidas a blocos indentados — são inequívocas e suportam dicas de linguagem. Tis (~~~) são úteis quando o código em si contém três crases. Sempre feche a cerca com o mesmo número de caracteres.

markdown
```
plain code block
multiple lines
```

~~~
also a fenced block
using tildes
~~~

Realce de Sintaxe

Adicione um identificador de linguagem logo depois da cerca de abertura para realce de sintaxe (ex.: js, python). A maioria dos renderizadores usa highlight.js ou Prism. Aliases comuns: js, ts, py, rb, sh, json, html, css. Se a linguagem for desconhecida, omita para monoespaçada simples.

markdown
```javascript
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};
```

```python
def greet(name):
    print(f"Hello, {name}!")
```

```bash
echo "Hello, $USER"
```

Cercas de Código Aninhadas

Para exibir crases dentro de um bloco de código, use uma cerca diferente (tis para conteúdo com crases, ou mais crases do que aparecem dentro). Quatro crases cercam conteúdo que contém três crases. A cerca de fechamento deve ter o mesmo comprimento da de abertura.

markdown
Use four backticks to wrap triple backticks:

````
```js
console.log("inside");
```
````

Or use tildes to wrap backtick content:

~~~
```js
code with backticks
```
~~~

Código em Listas

Blocos de código cerca dentro de itens de lista devem ser indentados para alinhar com o texto da lista (tipicamente 3 espaços para listas com -, 4 para listas com 1.). Blocos indentados dentro de listas precisam de 8 espaços (4 da lista + 4 do código). Acertar o alinhamento é uma das tarefas mais delicadas do Markdown.

markdown
1. Item with code:

   ```
   code block indented to align
   ```

2. Next item with inline `code`.

- Or indent code 4 spaces beyond
      the list marker (8 total).
08

Citações (Blockquotes)

Citação Básica

O caractere > inicia uma citação. Você pode prefixar todas as linhas ou apenas a primeira — a maioria dos parsers une linhas consecutivas. Citações são renderizadas como citações indentadas e estilizadas (<blockquote>). Use-as para citações, destaques e trechos importantes.

markdown
> This is a blockquote.
> It can span multiple lines.

> Or just prefix the first line
and continuation lines without >
will still be part of the quote.

Citação de Múltiplas Linhas

Use linhas com > em branco para separar parágrafos dentro de uma citação (caso contrário eles se fundem). O > numa linha em branco mantém a citação aberta. Sem linhas em branco entre parágrafos, o texto flui como um único parágrafo. Sempre feche com uma linha normal.

markdown
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.

End of quote.

Citações Aninhadas

Vários caracteres > criam citações aninhadas (>> para dois níveis, >>> para três). Adicione espaços para legibilidade. Aninhamento profundo (3+ níveis) fica difícil de ler e estilizar — prefira achatar. Cada nível adiciona indentação na saída HTML.

markdown
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer

> Outer
>> Deeper
>>> Deepest level

Citações com Outros Elementos

Citações podem conter a maioria dos elementos Markdown: títulos, listas, código, ênfase, até tabelas. Prefixe cada linha com > (e um espaço) para mantê-las dentro da citação. Isso torna as citações poderosas para destaques, mas conteúdo complexo exige alinhamento cuidadoso do >.

markdown
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```

Citação com Atribuição

O Markdown não tem sintaxe formal de citação de fonte. Convenções comuns: prefixe o autor com um travessão numa nova linha, ou use HTML <blockquote> com <footer> e <cite> para citações semânticas. Para citações acadêmicas, considere uma nota de rodapé com a fonte.

markdown
> Be the change you wish to see
> in the world.

> — Mahatma Gandhi

> "Simplicity is the soul of efficiency."
> — Austin Freeman

<blockquote>
  <p>Quote text.</p>
  <footer>— <cite>Author</cite></footer>
</blockquote>
09

Tabelas

Tabela Básica

Tabelas usam barras verticais (|) para separar colunas e hífens para separar o cabeçalho. A linha de cabeçalho é obrigatória. Barras nas bordas das linhas são opcionais, mas melhoram a leitura. A largura das colunas não importa — as células se ajustam. Tabelas são uma extensão do GitHub Flavored Markdown.

markdown
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | NYC      |
| Bob   | 25  | London   |
| Carol | 35  | Paris    |

Alinhamento de Células

Dois-pontos na linha separadora controlam o alinhamento: :--- esquerda, :---: centro, ---: direita. Sem dois-pontos, o padrão é à esquerda. O alinhamento se aplica à coluna inteira e define o text-align CSS na saída HTML. Útil para colunas numéricas (à direita) e cabeçalhos (centralizados).

markdown
| Left   | Center | Right  |
|:-------|:------:|-------:|
| left   | center | right  |
| L      | C      | R      |

| Default | alignment |
|---------|-----------|
| no mark | left      |

Tabela com Formatação

Células podem conter Markdown inline: negrito, itálico, código, links, riscado, emoji. Elementos de bloco (títulos, listas, blocos de código) não funcionam dentro de células — use HTML se necessário. Mantenha o conteúdo das células curto para facilitar a leitura. Escape barras verticais com barra invertida para exibi-las literalmente.

markdown
| Feature    | Status | Notes              |
|------------|:------:|--------------------|
| **Bold**   | done   | *finished*         |
| `code`     | wip    | [docs](docs.md)    |
| ~~old~~    | removed| gone in v2         |
| [link][1]  | done   | see [ref][1]       |

Tabela Complexa

Tabelas escalam para muitas linhas e colunas, mas permanecem simples por célula. Para code spans com vírgulas, envolva em crases. Escape barras verticais literais com barra invertida e pipe. Dados complexos (células multilinha, tabelas aninhadas) exigem HTML <table>. Considere uma lista se a tabela ficar larga demais.

markdown
| Name  | Role    | Skills              | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead    | `js`, `ts`, `go`   | yes       |
| Bob   | Junior  | `py`, `sql`         | no        |
| Carol | Senior  | `rust`, `c++`       | yes       |

Escaped pipe: \| literal

Dicas e Limitações de Tabelas

Tabelas Markdown têm limites: sem mesclagem de células, sem conteúdo multilinha, sem elementos de bloco, sem tabelas aninhadas. Para isso, use HTML puro. Mantenha tabelas pequenas e escaneáveis. Se uma tabela precisar de notas de rodapé ou texto longo, divida-a. Ferramentas como TablesGenerator.com ajudam a criá-las rápido.

markdown
| A | B |
|---|---|
| 1 | 2 |

Tip: Use \| to escape pipes.

Limitation: no multi-line cells,
no blockquotes, no lists in cells.

For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>
10

Notas de Rodapé

Notas de Rodapé Básicas

Notas de rodapé usam marcadores [^id] no texto e [^id]: definição em outro lugar. O id pode ser um número ou uma palavra. Os renderizadores criam números sobrescritos clicáveis e uma seção de notas no fim. Suportado por GFM, Pandoc e a maioria dos parsers modernos.

markdown
Here is a sentence with a footnote.[^1]

[^1]: This is the footnote text.

Another sentence.[^note]

[^note]: Footnotes can use named labels.

Múltiplas Referências

Uma nota de rodapé pode ser referenciada várias vezes — cada [^id] aponta para a mesma definição. Linhas de continuação da definição são indentadas. A primeira referência costuma receber o número sobrescrito; as seguintes apontam para a mesma nota.

markdown
Use the term[^term] twice[^term] in the text.

[^term]: A single definition referenced
    multiple times.

First[^1] and second[^1] reference.

[^1]: One definition, two links back.

Notas de Rodapé Inline

Notas de rodapé inline (^[texto]) embutem o conteúdo da nota direto na referência, suportadas por Pandoc e algumas extensões (não no núcleo do GFM). Elas mantêm tudo num lugar só, mas podem interromper o fluxo de leitura. Use-as para notas curtas; notas longas funcionam melhor como referências.

markdown
Here is an inline footnote^[The note text
right here in the body.] in a sentence.

Pandoc also supports: ^[inline notes].

And another[^1].

[^1]: Traditional reference style.

Posicionamento das Notas

Definições de notas de rodapé podem ficar em qualquer lugar do documento — os renderizadores as coletam e exibem no fim. Indente linhas de continuação (4 espaços). Notas funcionam dentro de citações e itens de lista. A posição no fonte não afeta a posição na saída.

markdown
Body text with a note.[^1]

More paragraphs here.

[^1]: Definitions can appear anywhere.
    They float to the bottom in output.

> Even inside blockquotes.[^2]

[^2]: The renderer collects all notes
    and renders them at the end.

Notas com Código e Formatação

Definições de notas de rodapé suportam Markdown inline (negrito, itálico, código) e conteúdo de múltiplos parágrafos (indente as linhas de continuação com 4 espaços). Blocos de código indentados dentro de notas precisam de 8 espaços. Mantenha as notas concisas — conteúdo técnico longo fica melhor no texto principal ou num apêndice.

markdown
See the API[^api] for details.

[^api]: Use `fetch('/api/data')` to call.
    Supports **bold** and *italic*.
    Multi-paragraph: indent each line.

    Code blocks need indentation:
        indented code inside footnote
11

Listas de Definições

Lista de Definições Básica

Listas de definições usam um termo numa linha e, depois, dois-pontos (:) seguidos da definição. Suportado por PHP Markdown Extra, Pandoc e algumas extensões (não no núcleo do GFM). Renderiza como <dl><dt><dd>. Útil para glossários e pares termo-definição.

markdown
Term
: Definition of the term.

Markdown
: A lightweight markup language.

HTML
: HyperText Markup Language.

Múltiplos Termos

Vários termos consecutivos (sem dois-pontos) podem compartilhar uma única definição. Cada termo vira um <dt>, e a definição um <dd>. Útil quando o mesmo conceito tem vários nomes ou apelidos. Mantenha os termos em linhas separadas.

markdown
CSS
Cascading Style Sheets
: A style sheet language.

JS
JavaScript
: A programming language.

Both terms
: Share one definition.

Múltiplas Descrições

Várias definições consecutivas (cada uma começando com dois-pontos) para um termo criam múltiplos elementos <dd>. Útil para listar vários significados ou aspectos distintos de um termo. Cada linha com dois-pontos é uma entrada de definição separada.

markdown
Markdown
: A markup language.
: A tool for writing for the web.

Apple
: A fruit.
: A technology company.

Listas de Definições Aninhadas

Listas de definições aninhadas exigem indentar a lista interna (2 a 4 espaços) dentro da definição externa. O suporte dos parsers varia — alguns renderizadores não lidam com aninhamento. Para estruturas hierárquicas de termos complexas, considere HTML <dl> por confiabilidade. Teste no seu renderizador alvo.

markdown
Term
: Definition one.

  Nested term
  : Nested definition.

: Definition two for top term.

Listas de Definições com Elementos de Bloco

Entradas de listas de definições podem conter múltiplos parágrafos, citações e blocos de código — indente a continuação com 4 espaços (além dos dois-pontos). Blocos de código dentro precisam de 8 espaços no total. É poderoso, mas frágil; conteúdo complexo é mais seguro em HTML <dl>.

markdown
Markdown
:   A markup language.

    With multiple paragraphs in the
    definition (indent 4 spaces).

    > Blockquote inside definition.

:   Second definition with code:

        indented code (8 spaces)
12

Sumário (TOC)

Sumário Automático

A maioria dos parsers não gera sumários automaticamente por padrão. Alguns (marked com o plugin toc, MDX) suportam placeholders [TOC] ou {:toc}. Ferramentas como Doctoc e markdown-toc os geram a partir dos títulos. Para sites estáticos, componentes de TOC leem as âncoras dos títulos em build ou runtime.

markdown
## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)

Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.

Sumário Manual

Um sumário manual é uma lista aninhada de links para as âncoras dos títulos. Os ids das âncoras derivam do texto do título (minúsculas, hífens no lugar de espaços, pontuação removida). Indente para refletir a hierarquia dos títulos. Atualize manualmente quando os títulos mudarem, ou use um gerador.

markdown
# My Document

## Contents
- [Intro](#intro)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
- [Usage](#usage)

## Intro
...

Regras de Geração de Âncoras

A geração de âncoras varia por parser. Regras comuns: minúsculas, espaços viram hífens, pontuação removida, manter alfanuméricos. O GitHub mantém emoji e algum unicode. Números e pontos costumam ser removidos. Na dúvida, inspecione o HTML renderizado para achar o id real.

markdown
## Hello World        -> #hello-world
## Hello, World!      -> #hello-world
## C++ & Rust         -> #c--rust
## Uber Heading       -> #uber-heading
## 1. Getting Started  -> #1-getting-started
## API v2.0           -> #api-v20

IDs de Âncora Personalizados

Para âncoras confiáveis, adicione IDs explícitos. A sintaxe de atributo {#id} funciona em Pandoc, marked e algumas extensões. O truque HTML <a id="..."> funciona em qualquer lugar — coloque-o antes ou dentro do título. IDs personalizados sobrevivem a mudanças no texto do título.

markdown
## Heading {#custom-id}

<a id="my-anchor"></a>
## Heading

## Heading<a id="also"></a>

[link to custom](#custom-id)

Navegação do TOC e Links de Volta

Links de 'voltar ao topo' melhoram a navegação em documentos longos. O HTML <details>/<summary> cria um sumário recolhível — ótimo para sidebars ou READMEs longos. Combine com links de âncora para navegação suave. Adicione scroll-margin-top no CSS para compensar cabeçalhos fixos.

markdown
## Section

Content here.

[Back to top](#table-of-contents)

---

<details>
<summary>Table of Contents</summary>

- [Section 1](#section-1)
- [Section 2](#section-2)
</details>
13

Emoji e Caracteres Especiais

Shortcodes de Emoji

Shortcodes de emoji (:name:) são suportados por GitHub/GitLab (usando o conjunto EmojiOne/Twemoji). Há milhares de emoji nomeados. Shortcodes são práticos mas não portáveis — podem ser renderizados literalmente em parsers não GFM. Use emoji Unicode puro para máxima compatibilidade.

markdown
:smile: :heart: :thumbsup: :rocket:

GFM supports shortcodes:
:sparkles: new feature :tada:

:checkered_flag: launch!
:bug: fixed issue #42

Emoji Comuns

A maioria dos editores e renderizadores modernos lida com emoji Unicode puro diretamente — basta colar. Shortcodes são específicos do GitHub. Emoji podem transmitir tom e status (check/cross para resultados, bug para bugs). Use-os com moderação em documentos formais; são ótimos em READMEs e changelogs.

markdown
:smile: smile    :heart: heart    :thumbsup: thumbsup
:rocket: rocket   :star: star     :warning: warning
:check: check    :x: cross       :bulb: bulb
:fire: fire      :tada: tada      :bug: bug
:book: book      :wrench: wrench  :zap: zap

Entidades HTML

Entidades HTML funcionam no Markdown, já que ele passa direto para HTML. Use &amp; para e-comercial literal (especialmente em URLs/atributos), &lt; &gt; para colchetes angulares, &copy; &reg; &trade; para símbolos. As formas numéricas (&#169;) e hexadecimais (&#x00A9;) cobrem qualquer caractere Unicode.

markdown
&amp;  &lt;  &gt;  &quot;  &apos;

&copy;  &reg;  &trade;

&mdash; &ndash; &hellip;

&#169;  &#x00A9;

Use &amp; to show a literal &.

Caracteres Especiais

O Markdown não converte pontuação simples em caracteres tipográficos (aspas curvas) por padrão — use entidades HTML ou cole Unicode. Travessões e aspas curvas melhoram a tipografia. Muitos editores corrigem isso automaticamente. Para setas e símbolos, entidades são as mais claras.

markdown
-- em dash (or &mdash;)
-- en dash (or &ndash;)
... ellipsis (or &hellip;)
' ' curly quotes (&lsquo; &rsquo;)
" " curly quotes (&ldquo; &rdquo;)
-> arrow (or &rarr;)
(tm) (r) (c)

Combinando Emoji e Markdown

Emoji combinam com cada um dos elementos Markdown: títulos, listas, negrito, links, citações. Eles adicionam pistas visuais a changelogs, READMEs e templates de issues. Mantenha o uso de emoji consistente (por exemplo, mantenha uma convenção no changelog). Evite emoji em escrita formal/acadêmica.

markdown
## New Features

- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs

**Status:** :white_check_mark: Ready

> :warning: **Warning:** Deprecated!

[:book: Read the docs](/docs)
14

Diagramas Mermaid

Fluxograma Mermaid

Mermaid é uma linguagem de diagramas baseada em texto, renderizada por GitHub, GitLab e muitos geradores de sites estáticos. Envolva o código Mermaid num bloco cerca mermaid. flowchart TD (de cima para baixo) ou LR (da esquerda para a direita) define a direção. Nós usam [], {}, () para formas diferentes.

markdown
```mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[Do it]
    B -->|No| D[Do not]
    C --> E[End]
    D --> E
```

Diagrama de Sequência Mermaid

Diagramas de sequência mostram interações entre participantes ao longo do tempo. ->> é uma seta sólida (requisição), -->> é uma seta tracejada (resposta). participant declara atores. Útil para documentar fluxos de API, protocolos e troca de mensagens. Renderizado automaticamente no GitHub.

markdown
```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!
    A->>B: How are you?
    B-->>A: Good, thanks!
```

Diagrama de Classes Mermaid

Diagramas de classes modelam estruturas orientadas a objetos. + significa público, - privado, # protegido. <|-- denota herança. O Mermaid suporta associações, composições e interfaces. Ótimo para documentar a arquitetura do código direto no Markdown.

markdown
```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog
```

Diagrama de Estados Mermaid

Diagramas de estados mostram transições de estado. [*] marca estados inicial/final. Setas rotulam transições com eventos (state --> state: event). Útil para documentar protocolos, estados de UI e ciclo de vida de objetos. stateDiagram-v2 é a sintaxe moderna.

markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Processing --> Error: fail
    Done --> [*]
    Error --> [*]
```

Gráfico de Gantt Mermaid

Gráficos de Gantt visualizam cronogramas de projetos. dateFormat define a análise de datas. Tarefas usam id, início, duração (ex.: 7d). 'after a1' encadeia tarefas. Seções agrupam tarefas relacionadas. Útil para READMEs e planos de projeto — renderizado automaticamente no GitHub sem ferramentas externas.

markdown
```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Spec        :a1, 2024-01-01, 7d
    Mockups     :after a1, 5d
    section Build
    Develop     :2024-01-13, 14d
    Test        :7d
```

Gráfico de Pizza Mermaid

Gráficos de pizza mostram proporções como porcentagens (valores são relativos). O título é opcional. Rótulos entre aspas, valores depois dos dois-pontos. O Mermaid também suporta git graphs, diagramas ER, journey maps e mapas mentais — cada um renderizável no Markdown em plataformas compatíveis.

markdown
```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 18
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9
```
15

GitHub Flavored Markdown

Listas de Tarefas (GFM)

Listas de tarefas do GitHub Flavored Markdown (GFM) renderizam checkboxes interativos no GitHub. [x] marcado, [ ] desmarcado. Funcionam em issues, PRs, comentários e READMEs. Barras de progresso aparecem nas listas de issues. A sintaxe hoje é amplamente suportada além do GitHub.

markdown
- [x] Done task
- [ ] Todo task
- [ ] Another todo

## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] Deploy

Riscado (GFM)

O GFM adiciona riscado (~~texto~~) ao Markdown padrão. Funciona entre linhas e combina com outras formatações. Renderiza como <del>. Originalmente uma extensão GFM, hoje nas adições da especificação CommonMark. Útil para mostrar edições e deprecações.

markdown
~~deleted text~~

old ~~price~~ new

~~this line is wrong~~

Combine: **bold ~~struck~~ text**

~~multi-line
strikethrough~~

Tabelas (GFM)

Tabelas são um recurso do GFM (não do Markdown original). A sintaxe com barras verticais, uma linha de cabeçalho e um separador é obrigatória. Tabelas GFM suportam alinhamento, formatação inline e barras escapadas. Para tabelas complexas (mesclagem, aninhamento), use HTML.

markdown
| Feature    | Status |
|------------|:------:|
| Tables     | yes    |
| Tasks      | yes    |
| Auto-links | yes    |

Tables are core to GFM, not in
the original Markdown spec.

Alertas do GitHub

Alertas do GitHub (2023+) usam um marcador [!TYPE] na primeira linha de uma citação: NOTE, TIP, IMPORTANT, WARNING, CAUTION. São renderizados com cores e ícones distintos no GitHub. Ótimos para destaques em READMEs e docs. A sintaxe é específica do GitHub.

markdown
> [!NOTE]
> Useful information that users
> should know.

> [!WARNING]
> Urgent info about risks.

> [!IMPORTANT]
> Key information.

> [!TIP]
> Helpful advice.

HTML Puro Não Permitido

O GFM filtra HTML puro por segurança — <script>, <style>, <title>, às vezes <iframe>, e handlers de eventos são removidos. Isso previne XSS em conteúdo gerado por usuários. HTML seguro como <details>, <kbd>, <sup> passa. Conheça a allow-list do seu renderizador ao misturar HTML.

markdown
GFM sanitizes some HTML tags:

<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>

These are stripped for security.

Links Automáticos (GFM)

O GFM cria links automáticos para URLs soltas (https://...) e domínios www. sem colchetes angulares. Para portabilidade, colchetes angulares (<url>) funcionam em cada um dos sabores. O link automático pode surpreender — use colchetes angulares quando quiser exibir uma URL literalmente com outro texto adjacente.

markdown
Visit https://example.com now.

www.google.com auto-links too.

<https://example.com> always works.

In GFM, bare URLs and www. links
become clickable automatically.
16

Sintaxe Estendida

Realce

A sintaxe de realce ==texto== é uma extensão (não está no GFM nem no CommonMark) — suportada por alguns parsers, como markdown-it com plugin. A tag HTML <mark> é universalmente suportada. Use realce para enfatizar termos-chave; o excesso reduz o impacto.

markdown
==highlighted text==

<mark>HTML highlight</mark>

Some parsers (not GFM core) support
==this syntax== for highlighting.

Use <mark> for universal support.

Subscrito e Sobrescrito

Subscrito (~texto~) e sobrescrito (^texto^) são extensões do Pandoc/markdown-it, não padrão. Para renderização universal, use HTML <sub>/<sup> ou Unicode. Úteis em conteúdo científico e matemático escrito em Markdown.

markdown
H~2~O (subscript)

x^2^ (superscript)

E = mc^2^

H~2~SO~4~

Pandoc/R Markdown support ~ and ^.

Sintaxe de Atributos

A sintaxe de atributos {#id .class key=val} (Pandoc, alguns plugins markdown-it) anexa atributos HTML a elementos. Útil para hooks de estilo, âncoras personalizadas e alvos de links. Não é portável — vira texto literal em parsers sem suporte. Use com moderação.

markdown
## Heading {#id .class}

![alt](img.png){width=50%}

[link](url){target=_blank}

> Quote {.callout}

Contêineres Personalizados

Contêineres personalizados (:::tipo ... :::) são suportados por VuePress, Docusaurus, VitePress e ferramentas de docs semelhantes. Renderizam como caixas de destaque estilizadas. O tipo mapeia para uma classe CSS. Ótimo para docs temáticos, mas não é portável para renderizadores Markdown simples.

markdown
:::note
This is a note container.
:::

:::warning
This is a warning.
:::

::: details Open me
Hidden content.
:::

Matemática e LaTeX (KaTeX)

O suporte a matemática depende do renderizador: o GitHub suporta $...$ inline e $$...$$ em bloco (com MathJax/KaTeX). Alguns parsers Markdown não suportam matemática. Para máxima compatibilidade, renderize fórmulas como imagens ou use MathJax diretamente. Útil para docs científicos e técnicos.

markdown
Inline: $E = mc^2$ in a sentence.

Block:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers support \( \) and
\[ \] delimiters too.
17

Ferramentas e Editores

VS Code

O VS Code tem pré-visualização de Markdown embutida e um rico ecossistema de extensões. Markdown All in One adiciona atalhos (negrito, TOC, preview). markdownlint impõe estilo. Preview Enhanced suporta diagramas, matemática e exportações. Configure quebra de linha automática para editar confortavelmente.

markdown
# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc

# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V

# Settings:
"[markdown]": {
  "editor.wordWrap": "on",
  "editor.quickSuggestions": true
}

Typora

Typora é um editor Markdown WYSIWYG popular — renderiza inline enquanto você digita, eliminando o fluxo de painéis divididos. Suporta GFM, tabelas, cercas de código, matemática e Mermaid. Exporta para muitos formatos via ferramentas embutidas. Pago, mas refinado; ótimo para fluxos focados em escrita.

markdown
Typora: a WYSIWYG Markdown editor.

- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS

Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italic

Obsidian

Obsidian guarda notas como arquivos Markdown locais, com recursos poderosos: wiki-links, backlinks, visualização em grafo e tags. Estende o Markdown com callouts, embeds e Dataview. Ideal para Zettelkasten e gestão de conhecimento pessoal. Gratuito para uso pessoal.

markdown
Obsidian: a Markdown knowledge base.

- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title

[[note|alias]] for renamed links.

Markdown Lint

markdownlint impõe estilo consistente em arquivos Markdown. Configure regras no .markdownlint.json. Desativações comuns: MD013 (comprimento de linha) para prosa, MD033 (HTML inline) quando HTML é necessário. MD040 lembra de marcar cercas de código com linguagem. Integra-se com CI e editores.

markdown
# .markdownlint.json (config)

{
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "default": true
}

# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs language

Pandoc

Pandoc é o 'canivete suíço' da conversão de documentos — Markdown para/de HTML, PDF, Word, LaTeX, EPUB, slides. Suporta extensões Markdown (citações, matemática, listas de definições, atributos raw). A flag -s cria documentos autônomos. Indispensável para fluxos acadêmicos e editoriais.

markdown
# Convert Markdown to many formats:

pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf

# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html

# With a table of contents:
pandoc input.md --toc -o output.html

# Support extensions:
pandoc -f markdown+smart input.md

Editores Online

Editores online são ótimos para edições rápidas e compartilhamento. StackEdit e Dillinger são editores solo completos. HackMD/HedgeDoc adicionam colaboração em tempo real. O editor web do GitHub tem aba Preview. Cada um suporta Markdown padrão; recursos GFM funcionam melhor no editor do GitHub.

markdown
Popular online Markdown editors:

- StackEdit (stackedit.io)
  Full-featured, syncs to cloud.

- Dillinger (dillinger.io)
  Clean, exports to many formats.

- HackMD / HedgeDoc
  Real-time collaborative editing.

- GitHub web editor
  Preview tab for .md files.

- Markdown Live Preview
  Lightweight, instant preview.
18

Boas Práticas

Legibilidade Primeiro

O princípio central do Markdown é a legibilidade como texto puro. Prefira a sintaxe mais legível: títulos com #, listas com -, **negrito**. Evite aninhamento excessivo e formatação demais. Se o fonte é agradável de ler num editor de texto, você está usando Markdown bem.

markdown
# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).

# Bad: hard to read raw
##Section or ***overkill***

Tip: Preview raw Markdown often.
If it reads well as text, it is good.

Comprimento de Linha e Quebra

Duas abordagens válidas: hard-wrap (uma frase por linha) dá diffs de git limpos e edição fácil; soft-wrap (um parágrafo por linha) evita retrabalho de reflow. Escolha uma por projeto e seja consistente. Configure a largura de quebra do editor (tipicamente 80-120 caracteres) de acordo.

markdown
# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.

# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.

# Many projects prefer one sentence
# per line for clean git diffs.

Consistência

O Markdown oferece várias sintaxes para o mesmo resultado (negrito ** vs __, listas - vs * vs +). Escolha uma convenção por projeto e imponha-a com markdownlint. Consistência reduz a carga cognitiva para leitores e contribuidores, e facilita o processamento automatizado.

markdown
# Pick one style and stick to it:

- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)

Consistent style is more
maintainable and professional.

Boas Práticas de Links

Use links por referência para URLs longas, para manter a prosa legível. Use links inline para referências curtas e locais. Texto de link descritivo melhora acessibilidade e SEO — evite 'clique aqui'. Títulos adicionam contexto como tooltips. Agrupe definições de referência no fim da seção ou do documento.

markdown
# Reference links for long URLs:
See the [docs][docs] for details.

[docs]: https://example.com/very/long/url

# Inline for short links:
Edit [index.js](index.js).

# Title for context:
[API](api.md "REST API reference")

Keep link text descriptive,
not 'click here' or 'link'.

Acessibilidade

Acessibilidade importa no Markdown: texto alternativo significativo para imagens (alt vazio para decorativas), texto de link descritivo (não 'clique aqui'), hierarquia de títulos correta (não pule níveis) e HTML semântico (kbd, abbr, cite) onde o Markdown não alcança. Leitores de tela dependem disso.

markdown
# Always add alt text to images:
![Diagram of the system](diagram.png)

# Empty alt for decorative images:
![](spacer.png)

# Descriptive link text:
[Read the installation guide](install.md)

# Avoid: [click here](url)
# Use heading hierarchy in order.

# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>

Erros Comuns

Armadilhas comuns: faltar linhas em branco ao redor de elementos de bloco (listas, citações, código), indentação inconsistente em listas aninhadas, cercas de código não fechadas e misturar tabs/espaços. Sempre visualize antes de publicar. Rode markdownlint para capturar problemas automaticamente. Teste no seu renderizador alvo.

markdown
# Missing blank line before lists:
Text
- item  # may merge with text!

# Fix:
Text

- item

# Unclosed code fence:
```
code
# (missing closing fence)

# Inconsistent list indentation:
- a
  - b (2 spaces)
   - c (3 spaces — may break)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.