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.
# 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.
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.
<!-- 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.
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).
---
***
___
* * *
Text above
---
Text belowFormataçã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.
**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.
*italic text*
_also italic_
*italic*
<em>HTML italic</em>
normal *italic* normalNegrito + 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.
***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.
~~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.
==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.
H~2~O is water
E = mc^2^
x^2^ + y^2^ = r^2^
1st^st^ January
CO~2~ emissionsListas
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.
- item one
- item two
- item three
* asterisk works too
+ plus sign also works
- sub-item (indent 2 spaces)
- another sub-itemListas 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.
1. first
2. second
3. third
1. auto-numbered
1. still increments
1. third item
10. starts at 10
11. nextListas 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.
1. top level
- nested unordered
- second nested
2. back to top
1. nested ordered
2. another
3. third top
- fruits
- apple
- granny smith
- bananaListas 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.
- [x] completed task
- [ ] incomplete task
- [ ] another todo
1. [x] done
2. [ ] not done
- [x] Write the docs
- [ ] Review PR
- [ ] DeployListas 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.
- tight item
- tight item
- tight item
- loose item
- loose item
- loose itemLista 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.
- First item
Second paragraph of first item.
- Second item
> A blockquote inside a list item.
>
> Must be indented to align.
- Third itemLinks
Links Inline
Links inline usam [texto](url). Um título opcional entre aspas aparece como tooltip ao passar o mouse. Links relativos funcionam para navegação interna do site. Links de âncora (#id) pulam para elementos com o id correspondente. A URL não pode conter espaços — use %20 para espaços.
[link text](https://example.com)
[link with title](https://example.com "Title here")
[relative link](/about)
[anchor](#section-id)Links por Referência
Links por referência mantêm o texto legível ao separar a URL. Defina referências em qualquer lugar do documento ([ref]: url). Definições de referência não são renderizadas. A forma implícita [texto][] usa o próprio texto como id da referência. Referências podem ser reutilizadas.
[link text][ref]
[ref]: https://example.com "Optional title"
[link text][1]
[1]: https://example.com
[link text]
[link text]: https://example.comLinks Automáticos e URLs
URLs soltas viram links automaticamente no GitHub Flavored Markdown. Para conformidade com o padrão, envolva URLs em colchetes angulares (<url>). A forma com colchetes angulares funciona em cada um dos sabores de Markdown. O link automático pode ser desativado em alguns parsers.
https://example.com
<https://example.com>
<http://www.google.com>
Auto-linking bare URLs is supported
in GFM: visit https://example.com now.Links Automáticos de E-mail
Endereços de e-mail entre colchetes angulares viram links mailto: clicáveis. A especificação original do Markdown já suportava a forma <text@domain>. Alguns renderizadores ofuscam endereços de e-mail para reduzir coleta de spam. Use um formulário de contato para melhor proteção contra spam em sites públicos.
<[email protected]>
Contact: <[email protected]>
<John Doe <[email protected]>>
Mailto links work in most renderers.Títulos de Links
Títulos de links aparecem como tooltips ao passar o mouse. Use aspas duplas ou simples em torno do título. Títulos são opcionais e servem apenas como dicas de UX/SEO. Eles não substituem o texto do link — leitores de tela podem ignorá-los. Mantenha os títulos concisos.
[hover for title](https://example.com "Example Site")
[reference with title][a]
[a]: https://example.com "Example Site"
[title with single quotes](https://example.com 'Single')Links Internos e de Âncora
Âncoras de títulos são geradas automaticamente a partir do texto do título (minúsculas, espaços viram hífens, pontuação removida) na maioria dos parsers. Para IDs personalizados, use HTML <a id="..."> ou a extensão de atributo {#id} (Pandoc/marked). Links de âncora são essenciais para sumários.
## Section Heading
[jump to Section](#section-heading)
[back to top](#top)
<a id="custom-id"></a>
[custom anchor](#custom-id)
## Heading {#explicit-id}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.


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.


Imagens com Link
Envolva uma imagem num link aninhando a sintaxe de imagem dentro da sintaxe de link: [](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.
[](https://example.com/full)
[](/)
[](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.
![alt text][img-ref]
[img-ref]: https://example.com/image.png "Title"
![alt][logo]
[logo]: /assets/logo.pngDimensõ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 {width=300}.
<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>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.
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.
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.
` 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.
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an imageCaracteres 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).
\\ backslash
\` backtick
\* asterisk
\_ underscore
\{ \} curly braces
\[ \] square brackets
\( \) parentheses
\# hash
\+ plus
\- minus
\. dot
\! exclamationBlocos 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.
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.
```
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.
```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.
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.
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).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.
> 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.
> 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.
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer
> Outer
>> Deeper
>>> Deepest levelCitaçõ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 >.
> ## 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.
> 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>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.
| 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).
| 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.
| 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.
| Name | Role | Skills | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead | `js`, `ts`, `go` | yes |
| Bob | Junior | `py`, `sql` | no |
| Carol | Senior | `rust`, `c++` | yes |
Escaped pipe: \| literalDicas 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.
| 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>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.
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.
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.
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.
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.
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 footnoteListas 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.
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.
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
: 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.
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
: A markup language.
With multiple paragraphs in the
definition (indent 4 spaces).
> Blockquote inside definition.
: Second definition with code:
indented code (8 spaces)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.
## 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.
# 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.
## 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-v20IDs 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.
## 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.
## Section
Content here.
[Back to top](#table-of-contents)
---
<details>
<summary>Table of Contents</summary>
- [Section 1](#section-1)
- [Section 2](#section-2)
</details>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.
:smile: :heart: :thumbsup: :rocket:
GFM supports shortcodes:
:sparkles: new feature :tada:
:checkered_flag: launch!
:bug: fixed issue #42Emoji 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.
: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: zapEntidades HTML
Entidades HTML funcionam no Markdown, já que ele passa direto para HTML. Use & para e-comercial literal (especialmente em URLs/atributos), < > para colchetes angulares, © ® ™ para símbolos. As formas numéricas (©) e hexadecimais (©) cobrem qualquer caractere Unicode.
& < > " '
© ® ™
— – …
© ©
Use & 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.
-- em dash (or —)
-- en dash (or –)
... ellipsis (or …)
' ' curly quotes (‘ ’)
" " curly quotes (“ ”)
-> arrow (or →)
(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.
## 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)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.
```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.
```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.
```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.
```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.
```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.
```mermaid
pie title Browser Market Share
"Chrome" : 65
"Safari" : 18
"Edge" : 5
"Firefox" : 3
"Other" : 9
```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.
- [x] Done task
- [ ] Todo task
- [ ] Another todo
## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] DeployRiscado (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.
~~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.
| 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.
> [!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.
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.
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.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.
==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.
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.
## Heading {#id .class}
{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.
:::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.
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.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.
# 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.
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 italicObsidian
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.
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.
# .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 languagePandoc
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.
# 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.mdEditores 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.
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.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.
# 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.
# 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.
# 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.
# 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.
# Always add alt text to images:

# Empty alt for decorative images:

# 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.
# 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)Snippets de Markdown relacionados
Copy-paste ready code for common tasks.
Headings
Six levels of ATX and Setext headings.
Links and Images
Inline, reference, and auto links plus images.
Code Blocks
Fenced, indented, and inline code.
Tables
GFM tables with column alignment.
Lists
Ordered, unordered, and nested lists.
Blockquotes
Single, multi-line, and nested quotes.
Emphasis
Italic, bold, strikethrough, and escaping.
Task Lists
GFM checkboxes for to-do items.
Was this helpful?