Guia de Sintaxe Markdown Básica
A sintaxe markdown básica reúne os 11 elementos de formatação que John Gruber definiu no documento de design original de 2004, e quase todos os aplicativos markdown em 2026 ainda suportam o conjunto completo. Os 11 elementos são títulos, parágrafos, quebras de linha, ênfase, citações, listas, código, linhas horizontais, links, imagens e escape de caracteres. Cada elemento usa sinais de pontuação que já estão no seu teclado, e cada um é convertido em uma tag HTML específica. Existem pequenas diferenças entre processadores, por isso este guia destaca as opções que renderizam de forma idêntica em qualquer lugar. Todos os exemplos abaixo podem ser colados direto em um editor markdown com visualização ao vivo, e o resultado renderizado aparece na tela enquanto você digita.
Títulos
Um título começa com 1 a 6 sinais de cerquilha (#) seguidos de um espaço, e a quantidade de sinais define o nível de H1 a H6.
# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
Cada linha é convertida na tag HTML correspondente: # Page Title renderiza como um elemento h1 e ###### Fine Print renderiza como um h6. No markdown títulos também têm uma sintaxe alternativa para os 2 primeiros níveis. Coloque qualquer quantidade de sinais de igual na linha abaixo do texto para um H1, ou qualquer quantidade de hífens para um H2. A forma com # é conhecida como estilo ATX; a forma sublinhada é conhecida como estilo Setext.
Heading level 1
===============
Heading level 2
---------------
Boa prática: deixe uma linha em branco antes e depois de cada título, e mantenha 1 espaço entre os sinais de cerquilha e o texto, para que o título renderize corretamente em todos os aplicativos.
Parágrafos
Um parágrafo é formado por uma ou mais linhas consecutivas de texto com uma linha em branco acima e abaixo, e não precisa de nenhum marcador.
The first paragraph ends here.
A blank line above this sentence starts a second paragraph.
O renderizador envolve cada bloco em uma tag p, então os 2 blocos acima viram 2 parágrafos HTML separados. Quebras simples dentro de um bloco se fundem em texto contínuo, o que significa que você pode quebrar as linhas do arquivo fonte em 80 caracteres e o resultado continua sendo um parágrafo único, sem interrupções.
Boa prática: mantenha todo parágrafo alinhado à margem esquerda, porque 4 ou mais espaços iniciais transformam o parágrafo em um bloco de código.
Quebras de Linha
Uma quebra de linha dentro de um parágrafo exige 2 ou mais espaços no final da linha, ou a tag HTML <br>.
This line ends with 2 trailing spaces.
This line appears directly below it.
This line ends with a br tag.<br>
This line also sits inside the same paragraph.
Os dois métodos renderizam um elemento br, então a segunda linha aparece logo abaixo da primeira, sem o espaçamento de parágrafo. Um retorno simples, sem nada depois, funde as 2 linhas em uma só. O CommonMark também aceita uma barra invertida no final como quebra, mas processadores mais antigos a ignoram, então as 2 opções portáveis continuam sendo os espaços finais e a tag <br>.
Boa prática: prefira a tag <br> quando a quebra precisar sobreviver a copiar e colar e à revisão de código, já que os espaços finais ficam invisíveis na tela da maioria dos editores.
Ênfase
No markdown negrito usa 2 asteriscos de cada lado, itálico usa 1, e negrito com itálico usa 3; underscores funcionam como alternativa equivalente ao redor de palavras inteiras.
This word is **bold** and so is this __word__.
This word is *italic* and so is this _word_.
This phrase is ***bold and italic***.
O renderizador converte os marcadores em tags strong e em: **bold** vira <strong>bold</strong>, *italic* vira <em>italic</em>, e o marcador triplo aninha uma tag dentro da outra. A ênfase também funciona dentro de uma palavra, então un*believ*able coloca em itálico apenas as 6 letras do meio.
Boa prática: use asteriscos em vez de underscores para ênfase no meio de palavras, porque todos os processadores importantes tratam asteriscos internos da mesma forma, enquanto underscores internos variam.
Citações
Uma citação começa com um sinal de maior (>) no início da linha, e cada linha citada carrega o próprio marcador.
> A single-paragraph quote needs 1 marker per line.
>
> A marked blank line continues the quote into a second paragraph.
>
>> Two markers push this paragraph 1 level deeper as a nested quote.
O resultado é um elemento blockquote, e o marcador duplo aninha uma segunda citação dentro da primeira. Citações também comportam outros elementos markdown. Um título, uma lista ou um texto em negrito renderiza normalmente dentro da citação quando cada linha começa com o marcador >, o que é ideal para e-mails citados e trechos com estrutura própria.
Boa prática: cerque toda citação com linhas em branco para que cada processador detecte exatamente onde a citação começa e termina.
Listas
No markdown listas ordenadas colocam um número e um ponto antes de cada item, e listas não ordenadas colocam um hífen, asterisco ou sinal de mais antes de cada item.
1. First step
2. Second step
3. Third step
1. Indented sub-step
- Bullet item
- Bullet item
- Nested bullet
Listas ordenadas renderizam como elementos ol e contam a partir do primeiro número digitado, então uma lista escrita como 1, 8, 3 ainda sai como 1, 2, 3. Listas não ordenadas renderizam como elementos ul com qualquer um dos 3 delimitadores. Um recuo de 4 espaços ou 1 tab aninha uma sublista, e o mesmo recuo mantém outros elementos dentro de um item da lista: um parágrafo ou citação precisa de 4 espaços, enquanto um bloco de código dentro de uma lista precisa de 8 espaços, porque o recuo padrão de 4 espaços do código se soma ao recuo da lista.
Boa prática: mantenha 1 único estilo de delimitador por lista e termine os números das listas ordenadas com pontos em vez de parênteses, já que a forma com ponto funciona em todos os aplicativos markdown.
Código
Código inline fica entre crases simples, e um bloco de código é qualquer sequência de linhas recuadas com pelo menos 4 espaços ou 1 tab.
Type `git status` to check the working tree.
<html>
<head></head>
</html>
O par de crases renderiza um elemento code em fonte monoespaçada, e o bloco recuado renderiza dentro das tags pre e code com cada espaço preservado. Um trecho que contém uma crase precisa de crases duplas ao redor, então the outer pair displays `code` literally. Blocos de código cercados por crases triplas pertencem à sintaxe estendida; o recuo de 4 espaços é o método original.
Boa prática: envolva crases literais em crases duplas para que o caractere interno seja impresso em vez de encerrar o trecho de código antes da hora.
Linhas Horizontais
Uma linha horizontal exige 3 ou mais asteriscos, hífens ou underscores sozinhos em uma linha própria.
***
---
___
As 3 versões renderizam um elemento hr idêntico, um divisor de largura total. O caractere pode se repetir além de 3 sem mudança no resultado, então uma linha de 20 hífens produz a mesma régua que 3. Escritores usam essas linhas para marcar mudanças de cena e limites de seção onde um título seria pesado demais.
Boa prática: deixe uma linha em branco acima e abaixo de cada linha horizontal, porque uma linha só de hífens colocada logo abaixo de um texto transforma esse texto em um título H2.
Links
Um link inline envolve o texto do link em colchetes e o segue imediatamente com a URL entre parênteses, além de um título opcional entre aspas.
Read the [original spec](https://daringfireball.net/projects/markdown/ "Gruber's 2004 spec").
Reference style keeps prose clean: read the [original spec][1].
[1]: https://daringfireball.net/projects/markdown/
Bare addresses work in angle brackets: <https://example.com> and <mail@example.com>
Toda forma renderiza um elemento a, e o texto do título aparece como tooltip ao passar o mouse. Links em estilo de referência separam a URL da frase: o rótulo [1] aponta para uma definição que pode ficar em qualquer lugar do arquivo, então um parágrafo cheio de URLs longas continua legível no texto fonte. Os sinais de menor e maior convertem uma URL crua ou endereço de e-mail em um link clicável sem nenhum texto extra. Links também aceitam formatação, então asteriscos ao redor da construção inteira deixam o link em negrito e crases dentro dos colchetes o renderizam como código.
Boa prática: codifique qualquer espaço dentro de uma URL como %20 para que o endereço completo sobreviva em todos os processadores.
Imagens
Uma imagem usa um ponto de exclamação, depois o texto alternativo entre colchetes e, em seguida, o caminho ou a URL da imagem entre parênteses.
[](https://example.com/report)
A primeira linha renderiza um elemento img com o texto alternativo como rótulo de acessibilidade e o título entre aspas como texto de hover. A sintaxe é igual à de um link com 1 caractere a mais na frente. A segunda linha aninha toda a construção da imagem dentro de um link, então um clique na figura abre a URL de destino.
Boa prática: escreva um texto alternativo que descreva o conteúdo da imagem, porque leitores de tela e mecanismos de busca o leem no lugar da figura.
Escape de Caracteres
Uma barra invertida () colocada antes de um caractere de formatação exibe esse caractere literalmente em vez de ativar sua função markdown.
\* This line shows a literal asterisk, not a bullet point.
1968\. The escaped period stops this year from starting an ordered list.
A barra invertida nunca aparece no resultado; apenas o caractere que vem depois dela é impresso. O markdown aceita escape com barra invertida para 12 caracteres: barra invertida, crase, asterisco, underscore, chaves, colchetes, parênteses, cerquilha, sinal de mais, sinal de menos, ponto e ponto de exclamação. O segundo exemplo acima resolve uma armadilha comum, já que qualquer linha que abre com um número e um ponto vira um item de lista sem o escape.
Boa prática: escape apenas os caracteres dessa lista de 12 itens, porque uma barra invertida antes de qualquer outro caractere é impressa como uma barra invertida visível.
Perguntas frequentes
O que é a sintaxe markdown básica?
A sintaxe básica é o conjunto de 11 elementos do documento de design markdown de 2004 de John Gruber, e quase todo aplicativo markdown suporta o conjunto inteiro. Os 11 elementos se comportam de forma consistente entre processadores, o que torna o conjunto básico a escolha mais segura para arquivos que circulam entre plataformas.
Quantos níveis de título o markdown suporta?
O markdown suporta 6 níveis de título, escritos com 1 a 6 sinais de cerquilha, e eles mapeiam diretamente para as tags HTML h1 a h6. A sintaxe alternativa sublinhada cobre apenas os 2 primeiros níveis: sinais de igual para H1 e hífens para H2.
Como adiciono uma quebra de linha sem começar um novo parágrafo?
Termine a linha com 2 espaços no final ou com a tag HTML <br>. Os dois renderizam um elemento br dentro do parágrafo atual. Uma linha em branco tem efeito diferente: ela fecha o parágrafo e abre um novo.
A sintaxe básica é suficiente ou preciso da sintaxe estendida?
A sintaxe básica cobre documentos padrão, enquanto a sintaxe estendida adiciona tabelas, blocos de código cercados, notas de rodapé e outros elementos de especificações posteriores, como o GFM. Comece pelo conjunto básico para ter compatibilidade máxima e adicione elementos estendidos quando souber que a plataforma de destino do usuário os suporta.