Guia de Sintaxe Markdown Básica

A sintaxe markdown básica é composta pelos 11 elementos de formatação que John Gruber definiu no documento de conceção original de 2004, e quase todas as aplicações markdown em 2026 continuam a suportar o conjunto completo. Os 11 elementos são títulos, parágrafos, quebras de linha, ênfase, citações, listas, código, linhas horizontais, ligações, imagens e escape de caracteres. Cada elemento usa sinais de pontuação que já estão no teclado do utilizador, e cada um converte-se numa tag HTML específica. Existem pequenas diferenças entre processadores, por isso este guia assinala as opções que renderizam de forma idêntica em todo o lado. Todos os exemplos abaixo podem ser colados diretamente num editor markdown com pré-visualização em tempo real, e o resultado renderizado aparece no ecrã à medida que escreve.

Títulos

Um título começa com 1 a 6 cardinais (#) seguidos de um espaço, e o número de cardinais 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 converte-se na tag HTML correspondente, pelo que # Page Title renderiza como um elemento h1 e ###### Fine Print renderiza como um h6. O markdown tem ainda uma sintaxe alternativa para os 2 níveis superiores. Coloque qualquer quantidade de sinais de igual na linha abaixo do texto para um H1, ou qualquer quantidade de hífenes 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 cardinais e o texto, para que o título renderize corretamente em todas as aplicações.

Parágrafos

Um parágrafo é uma ou mais linhas consecutivas de texto com uma linha em branco acima e abaixo, e não precisa de qualquer marcador.

The first paragraph ends here.

A blank line above this sentence starts a second paragraph.

O renderizador envolve cada bloco numa tag p, pelo que os 2 blocos acima se tornam 2 parágrafos HTML separados. As mudanças de linha simples dentro de um bloco fundem-se em texto contínuo, o que significa que pode quebrar as linhas do ficheiro fonte aos 80 caracteres e o resultado continua a ser um único parágrafo ininterrupto.

Boa prática: mantenha todos os parágrafos encostados à margem esquerda, porque 4 ou mais espaços iniciais transformam um parágrafo num bloco de código.

Quebras de Linha

Uma quebra de linha dentro de um parágrafo exige 2 ou mais espaços no final de uma 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.

Ambos os métodos renderizam um elemento br, pelo que a segunda linha fica diretamente por baixo da primeira sem o espaçamento de um novo parágrafo. Uma mudança de linha simples sem nada a seguir funde as 2 linhas numa só. O CommonMark também aceita uma barra invertida final como quebra, mas os processadores mais antigos ignoram-na, por isso as 2 opções portáveis continuam a ser os espaços finais e a tag <br>.

Boa prática: escolha a tag <br> quando uma quebra tiver de sobreviver ao copiar e colar e à revisão de código, já que os espaços finais ficam invisíveis na maioria dos editores.

Ênfase

O negrito em markdown leva 2 asteriscos de cada lado, o itálico leva 1 e o negrito itálico leva 3; os underscores servem como alternativa equivalente à volta 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** torna-se <strong>bold</strong>, *italic* torna-se <em>italic</em>, e o marcador triplo aninha uma tag dentro da outra. A ênfase também funciona dentro de uma palavra, pelo que 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 uma palavra, porque todos os processadores principais tratam os asteriscos interiores da mesma forma, enquanto os underscores interiores variam.

Citações

Uma citação começa com um sinal de maior (>) no início de uma linha, e cada linha citada leva o seu 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. As citações também comportam outro markdown. Um título, uma lista ou texto em negrito renderizam normalmente dentro da citação quando cada uma das suas linhas começa com o marcador >, o que é ideal para emails citados e passagens citadas com estrutura própria.

Boa prática: rodeie todas as citações com linhas em branco, para que cada processador detete exatamente onde a citação começa e termina.

Listas

Uma lista ordenada coloca um número e um ponto antes de cada item, e uma lista não ordenada coloca um hífen, um asterisco ou um 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

As listas ordenadas renderizam como elementos ol e contam a partir do primeiro número que escrever, pelo que uma lista escrita como 1, 8, 3 produz na mesma 1, 2, 3. As listas markdown não ordenadas renderizam como elementos ul com qualquer um dos 3 delimitadores. Uma indentação de 4 espaços ou 1 tabulação aninha uma sublista, e a mesma indentação mantém outros elementos dentro de um item da lista: um parágrafo ou uma citação precisam de 4 espaços, enquanto um bloco de código dentro de uma lista precisa de 8 espaços, porque a indentação padrão de 4 espaços do código se soma à indentação da lista.

Boa prática: mantenha 1 único estilo de delimitador por lista e termine os números ordenados com ponto em vez de parêntese, já que a forma com ponto funciona em todas as aplicações markdown.

Código

O código inline fica entre backticks simples, e um bloco de código é qualquer sequência de linhas indentadas com pelo menos 4 espaços ou 1 tabulação.

Type `git status` to check the working tree.

    <html>
      <head></head>
    </html>

O par de backticks renderiza um elemento code num tipo de letra monoespaçado, e o bloco indentado renderiza dentro de tags pre e code com todos os espaços preservados. Um excerto que contenha ele próprio um backtick precisa de backticks duplos à volta, pelo que the outer pair displays `code` literally. Os blocos de código delimitados por 3 backticks pertencem à sintaxe estendida; a indentação de 4 espaços é o método original.

Boa prática: envolva os backticks literais em backticks duplos, para que o carácter interior seja impresso em vez de fechar o trecho de código antes de tempo.

Linhas Horizontais

Uma linha horizontal exige 3 ou mais asteriscos, hífenes ou underscores sozinhos na sua própria linha.

***

---

___

As 3 versões renderizam um elemento hr idêntico, um divisor de largura total. O carácter pode repetir-se para lá de 3 sem qualquer alteração no resultado, pelo que uma linha de 20 hífenes produz a mesma régua que 3. Quem escreve usa estas linhas para marcar mudanças de cena e fronteiras de secçã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ífenes colocada diretamente por baixo de um texto transforma esse texto num título H2.

Ligações

Uma ligação inline envolve o texto da ligação em parênteses retos e fá-lo seguir imediatamente do URL entre parênteses curvos, mais 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>

Todas as formas renderizam um elemento a, e o texto do título aparece como tooltip ao passar o rato. As ligações em estilo de referência separam o URL da frase: a etiqueta [1] aponta para uma definição que pode ficar em qualquer ponto do ficheiro, pelo que um parágrafo cheio de URLs longos se mantém legível na fonte. Os parênteses angulares convertem um URL ou um endereço de email em bruto numa ligação clicável sem texto adicional. As ligações também aceitam formatação, pelo que asteriscos à volta de toda a construção colocam a ligação a negrito e backticks dentro dos parênteses retos renderizam-na como código.

Boa prática: codifique qualquer espaço dentro de um 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 parênteses retos, depois o caminho ou URL da imagem entre parênteses curvos.

![Chart of 2026 traffic](/images/traffic-chart.png "Monthly sessions")

[![Chart of 2026 traffic](/images/traffic-chart.png)](https://example.com/report)

A primeira linha renderiza um elemento img com o texto alternativo como etiqueta de acessibilidade e o título entre aspas como texto ao passar o rato. A sintaxe corresponde à de uma ligação com 1 carácter extra à frente. A segunda linha aninha toda a construção da imagem dentro de uma ligação, pelo que um clique na imagem abre o URL de destino.

Boa prática: escreva um texto alternativo que descreva o conteúdo da imagem, porque os leitores de ecrã e os motores de pesquisa leem-no no lugar da imagem.

Escape de Caracteres

Uma barra invertida () colocada antes de um carácter de formatação mostra esse carácter literalmente em vez de ativar a 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; só o carácter a seguir a ela é impresso. O markdown aceita o escape com barra invertida para 12 caracteres: barra invertida, backtick, asterisco, underscore, chavetas, parênteses retos, parênteses curvos, cardinal, 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 comece com um número e um ponto se torna um item de lista sem o escape.

Boa prática: aplique o escape apenas aos caracteres dessa lista de 12 itens, porque uma barra invertida antes de qualquer outro carácter é impressa como uma barra visível.

Perguntas frequentes

O que é a sintaxe markdown básica?

A sintaxe básica é o conjunto de 11 elementos do documento de conceção markdown de John Gruber de 2004, e quase todas as aplicações markdown suportam a totalidade. Os 11 elementos comportam-se de forma consistente entre processadores, o que faz do conjunto básico a escolha mais segura para documentos que circulam entre plataformas.

Quantos níveis de título suporta o markdown?

O markdown suporta 6 níveis de título, escritos com 1 a 6 cardinais, e correspondem diretamente às tags HTML h1 a h6. A sintaxe alternativa sublinhada cobre apenas os 2 níveis superiores: sinais de igual para o H1 e hífenes para o H2.

Como adiciono uma quebra de linha sem iniciar um novo parágrafo?

Termine a linha com 2 espaços finais ou com a tag HTML <br>. Ambos renderizam um elemento br dentro do parágrafo atual. Uma linha em branco tem um efeito diferente: fecha o parágrafo e abre um novo.

A sintaxe básica chega, ou preciso da sintaxe estendida?

A sintaxe básica cobre os documentos comuns, enquanto a sintaxe estendida acrescenta tabelas, blocos de código delimitados, notas de rodapé e outros elementos de especificações posteriores como o GFM. Comece pelo conjunto básico para máxima compatibilidade, e acrescente depois os elementos estendidos quando souber que a plataforma de destino os suporta.