Sintaxe Básica do Markdown: Guia Completo com Exemplos
Domine todos os elementos da sintaxe básica do Markdown com exemplos claros e erros comuns a evitar. Sua referência definitiva para títulos, listas, links e muito mais.
A sintaxe básica do Markdown é a base que todo desenvolvedor, escritor e criador de conteúdo precisa dominar. Seja escrevendo documentação, elaborando um artigo de blog ou formatando uma issue no GitHub, esses elementos fundamentais são os blocos de construção que você usará todos os dias.
Este guia aborda cada elemento da sintaxe básica com exemplos claros, comparações com a saída HTML e erros comuns a evitar. Salve nos favoritos — você vai voltar aqui com mais frequência do que imagina.
Títulos
Os títulos estruturam seu conteúdo em uma hierarquia lógica. O Markdown suporta seis níveis de títulos, criados colocando símbolos # antes do texto.
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6
Isso produz o seguinte HTML:
<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>
Boas Práticas para Títulos
Sempre adicione um espaço entre o # e o texto do título. Sem o espaço, alguns interpretadores não reconhecerão como um título.
✅ ## This Works
❌ ##This Doesn't
Use os títulos em ordem. Não pule de H2 para H4 — isso quebra a estrutura lógica do documento e prejudica tanto a acessibilidade quanto o SEO. Pense nos títulos como um sumário: cada nível deve se aninhar logicamente sob o nível acima.
Use apenas um H1 por página. O H1 é o título da sua página. Todo o restante deve ser H2 ou inferior.
Parágrafos e Quebras de Linha
Parágrafos são o elemento mais simples do Markdown — basta escrever texto. Separe os parágrafos com uma linha em branco.
This is the first paragraph.
This is the second paragraph.
Quebras de Linha
É aqui que muitos iniciantes se confundem. Pressionar Enter uma vez não cria uma nova linha na maioria dos renderizadores Markdown. Você precisa:
- Terminar a linha com dois ou mais espaços (e depois pressionar Enter)
- Usar a tag HTML
<br>
This is the first line.
This is the second line.
Or use HTML:<br>
This starts a new line.
Erro Comum
Simplesmente pressionar Enter entre duas linhas vai mesclá-las em um único parágrafo na saída renderizada:
Line one
Line two
Isso é renderizado como: "Line one Line two" — uma única linha. Sempre use uma linha em branco para um novo parágrafo ou espaços no final da linha para uma quebra de linha dentro do mesmo parágrafo.
Formatação de Texto
O Markdown torna muito fácil enfatizar texto. Aqui estão as principais opções de formatação:
Negrito
Envolva o texto com asteriscos duplos ou sublinhados duplos:
**This is bold text**
__This is also bold__
Saída HTML: <strong>This is bold text</strong>
Itálico
Envolva o texto com asteriscos simples ou sublinhados simples:
*This is italic text*
_This is also italic_
Saída HTML: <em>This is italic text</em>
Negrito e Itálico
Combine três asteriscos para ambos:
***Bold and italic***
___Also bold and italic___
**_Or mix like this_**
Saída HTML: <strong><em>Bold and italic</em></strong>
Tachado
Use dois tils (esta é uma extensão do GFM, mas suportada em quase todos os lugares):
~~This text is crossed out~~
Saída HTML: <del>This text is crossed out</del>
Erro Comum
Usar sublinhados no meio de uma palavra não funciona de forma confiável. Prefira asteriscos para ênfase no meio de palavras:
✅ This is**very**important
❌ This is__very__important
Citações em Bloco
As citações em bloco são criadas com o caractere >. Elas são comumente usadas para citar fontes, destacar notas importantes ou chamar atenção para informações-chave.
> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber
Saída HTML:
<blockquote>
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
— John Gruber</p>
</blockquote>
Citações com Múltiplos Parágrafos
Adicione > na linha em branco entre os parágrafos:
> First paragraph of the quote.
>
> Second paragraph of the quote.
Citações Aninhadas
Use >> para aninhar:
> This is the outer quote.
>
>> This is a nested quote inside it.
Citações com Outros Elementos
Você pode combinar citações em bloco com outras formatações do Markdown:
> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.
Listas
As listas são um dos elementos mais usados no Markdown. Você encontrará três tipos: não ordenadas, ordenadas e listas de tarefas.
Listas Não Ordenadas
Use -, * ou + como marcadores. Escolha um e mantenha a consistência:
- First item
- Second item
- Third item
Saída HTML:
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>
Listas Ordenadas
Use números seguidos de um ponto. Os números em si não importam — o Markdown os numera automaticamente:
1. First step
2. Second step
3. Third step
Curiosamente, isso produz a mesma saída:
1. First step
1. Second step
1. Third step
Ambos são renderizados como uma lista numerada de 1 a 3. No entanto, a melhor prática é usar números sequenciais para facilitar a leitura no arquivo-fonte.
Listas Aninhadas
Indente com dois ou quatro espaços para criar sublistas:
1. Main item
- Sub-item A
- Sub-item B
- Sub-sub-item
2. Another main item
Listas de Tarefas
As listas de tarefas (um recurso do GFM) usam - [ ] para itens desmarcados e - [x] para itens marcados:
- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish
Erro Comum
Esquecer a linha em branco antes de uma lista quando ela vem depois de um parágrafo. Alguns interpretadores exigem isso:
✅ Here is my list:
- Item one
- Item two
❌ Here is my list:
- Item one
- Item two
Código
Exibir código é um dos pontos fortes do Markdown, e fazer isso corretamente é fundamental para a legibilidade.
Código Inline
Envolva o código em crases simples para exibição inline:
Use the `print()` function to output text.
Saída HTML: Use the <code>print()</code> function to output text.
Se o próprio código contiver uma crase, use crases duplas:
``There is a literal `backtick` here.``
Blocos de Código
Para código com múltiplas linhas, use três crases (blocos de código cercados) com um identificador de linguagem opcional para destaque de sintaxe:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
O identificador de linguagem (javascript, python, html, css, bash, etc.) ativa o destaque de sintaxe na maioria dos renderizadores. Sempre inclua-o — isso melhora drasticamente a legibilidade.
Blocos de Código Indentados
Você também pode criar blocos de código indentando cada linha com quatro espaços ou uma tabulação:
function add(a, b) {
return a + b;
}
No entanto, blocos de código cercados são fortemente recomendados porque suportam destaque de sintaxe e não exigem que cada linha seja indentada.
Links
Links são essenciais para conectar conteúdo. O Markdown suporta diversos formatos de link.
Links Inline
O formato mais comum — texto entre colchetes, URL entre parênteses:
[Visit Example](https://example.com)
Saída HTML: <a href="https://example.com">Visit Example</a>
Links com Títulos
Adicione um título entre aspas após a URL (aparece como tooltip ao passar o mouse):
[Visit Example](https://example.com "Example Website")
Links de Referência
Para um texto-fonte mais limpo quando você tem muitos links, use o estilo de referência:
I use [Google][1] and [GitHub][2] daily.
[1]: https://google.com "Google"
[2]: https://github.com "GitHub"
Isso mantém seus parágrafos limpos e agrupa todas as URLs no final — especialmente útil em documentos longos.
Links Automáticos
Envolva uma URL ou e-mail em colchetes angulares para link automático:
<https://example.com>
<contact@example.com>
A maioria dos renderizadores modernos (como o GitHub) também faz link automático de URLs sem colchetes angulares, mas usá-los garante compatibilidade.
Erro Comum
Esquecer que espaços em URLs precisam de codificação. Use %20 para espaços:
✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)
Imagens
As imagens usam a mesma sintaxe dos links, mas com um ponto de exclamação ! na frente:
Saída HTML: <img src="/path/to/image.webp" alt="Alt text describing the image">
Imagens com Títulos
Imagens com Link
Combine a sintaxe de link e imagem para tornar uma imagem clicável:
[](https://example.com)
Boas Práticas para Texto Alternativo
Sempre escreva um texto alternativo descritivo. Ele serve a dois propósitos essenciais:
- Acessibilidade — leitores de tela o utilizam para descrever imagens a usuários com deficiência visual
- SEO — mecanismos de busca o utilizam para entender o conteúdo da imagem
✅ 
❌ 
❌ 
Linhas Horizontais
Crie uma linha horizontal (separação temática) para separar visualmente seções. Use três ou mais hifens, asteriscos ou sublinhados:
---
***
___
Todos os três produzem o mesmo HTML: <hr>
Melhor prática: Use --- de forma consistente e sempre adicione linhas em branco antes e depois:
Content above the rule.
---
Content below the rule.
Escapando Caracteres
E se você quiser exibir um asterisco ou símbolo de cerquilha literal sem ativar a formatação do Markdown? Use uma barra invertida \ antes do caractere:
\* This is not italic \*
\# This is not a heading
\- This is not a list item
Aqui está a lista completa de caracteres que podem ser escapados:
\ Backslash
` Backtick
* Asterisk
_ Underscore
{} Curly braces
[] Square brackets
() Parentheses
# Hash
+ Plus sign
- Hyphen
. Dot
! Exclamation mark
| Pipe
Tabela de Referência Rápida
Aqui está cada elemento da sintaxe básica em uma tabela para consulta rápida:
Element Syntax HTML
-------------- ------------------ -----------
Heading 1 # Text <h1>
Heading 2 ## Text <h2>
Heading 3 ### Text <h3>
Bold **text** <strong>
Italic *text* <em>
Bold + Italic ***text*** <strong><em>
Strikethrough ~~text~~ <del>
Blockquote > text <blockquote>
Ordered list 1. item <ol><li>
Unordered list - item <ul><li>
Inline code `code` <code>
Link [text](url) <a href>
Image  <img>
Horizontal rule --- <hr>
Line break spaces + Enter <br>
Coloque em Prática
Agora que você aprendeu todos os elementos da sintaxe básica do Markdown, é hora de usá-los. Veja o que fazer a seguir:
-
Pratique escrevendo: Crie um arquivo
notes.mde experimente cada elemento da sintaxe. Quanto mais você escrever, mais natural se torna. -
Use uma ferramenta de pré-visualização: A pré-visualização integrada do VS Code (
Ctrl+Shift+V/Cmd+Shift+V) permite ver a saída renderizada em tempo real enquanto você digita. -
Converta e compartilhe: Quando seu documento Markdown estiver pronto para o mundo, transforme-o em uma saída polida — converta Markdown para HTML para publicação web, gere um PDF para documentos prontos para impressão, ou exporte para Word para edição colaborativa.
-
Explore mais: Quando estiver confortável com a sintaxe básica, aprofunde-se no nosso guia de sintaxe estendida do Markdown para tabelas, notas de rodapé, listas de definição e muito mais. Novo no Markdown? Comece com O Que é Markdown para uma visão geral.
A beleza do Markdown é que esses elementos básicos cobrem a grande maioria de tudo o que você precisará escrever. Domine-os uma vez e você os usará em todo lugar — do GitHub ao Notion, da documentação a artigos de blog como este.