Guia de Referência Markdown: Guia Completo de Sintaxe

· 12 min de leitura

Índice

O Que É Markdown?

Markdown é uma linguagem de marcação leve criada por John Gruber e Aaron Swartz em 2004 que revolucionou a forma como escrevemos para a web. Ela permite formatar texto simples usando sintaxe simples e intuitiva que é tanto legível por humanos quanto analisável por máquinas.

Ao contrário do HTML, que requer tags verbosas e elementos de fechamento, o Markdown usa símbolos naturais como asteriscos, hashes e colchetes. Isso torna a escrita mais rápida e o texto fonte legível mesmo sem renderização. Um documento Markdown parece limpo e lógico em sua forma bruta, razão pela qual se tornou o padrão universal para documentação técnica.

A filosofia por trás do Markdown é simples: escrever deve ser fácil, e a sintaxe deve ser invisível. Quando você lê um arquivo Markdown, está lendo conteúdo primeiro, marcação depois. Isso é fundamentalmente diferente das linguagens de marcação tradicionais onde as tags frequentemente obscurecem o conteúdo real.

Onde o Markdown É Usado

O Markdown se tornou onipresente em todo o ecossistema tecnológico e além:

Precisa converter seu Markdown para HTML para publicação web? Experimente nosso conversor de Markdown para HTML para conversão instantânea e precisa.

Dica profissional: Arquivos Markdown usam a extensão .md ou .markdown. A maioria das plataformas reconhece ambas, mas .md é mais comum e concisa.

Títulos e Estrutura do Documento

Os títulos são a espinha dorsal da estrutura do documento em Markdown. Eles criam hierarquia, melhoram a legibilidade e ajudam tanto humanos quanto mecanismos de busca a entender a organização do seu conteúdo.

Sintaxe Básica de Títulos

O Markdown suporta seis níveis de títulos usando símbolos de hash (#). O número de hashes determina o nível do título:

# Título 1 (H1)
## Título 2 (H2)
### Título 3 (H3)
#### Título 4 (H4)
##### Título 5 (H5)
###### Título 6 (H6)

Cada nível de título tem significado semântico. H1 é o título do seu documento, H2s são seções principais, H3s são subseções, e assim por diante. Esta hierarquia é crucial para acessibilidade e SEO.

Sintaxe Alternativa para H1 e H2

O Markdown também suporta uma sintaxe alternativa de "sublinhado" para títulos H1 e H2:

Título 1
=========

Título 2
---------

Embora esta sintaxe seja válida, a sintaxe de hash é mais comum e suporta todos os seis níveis de título. A maioria dos desenvolvedores prefere a consistência de usar hashes em todos os seus documentos.

Melhores Práticas para Títulos

Dica rápida: Muitos analisadores Markdown geram automaticamente links âncora a partir de títulos, convertendo "Começando" para #começando. Isso permite vinculação profunda a seções específicas.

Formatação de Texto e Ênfase

O Markdown fornece sintaxe intuitiva para necessidades comuns de formatação de texto. Essas opções de formatação funcionam inline dentro de parágrafos e podem ser combinadas para estilização mais complexa.

Texto em Negrito e Itálico

A ênfase é criada usando asteriscos ou sublinhados:

**Texto em negrito** ou __Texto em negrito__
*Texto em itálico* ou _Texto em itálico_
***Negrito e itálico*** ou ___Negrito e itálico___

Tanto asteriscos quanto sublinhados funcionam de forma idêntica, mas asteriscos são mais comuns. Escolha um estilo e mantenha-o para consistência. Muitos guias de estilo recomendam asteriscos porque são mais fáceis de digitar e mais visualmente distintos.

Tachado e Outras Formatações

Opções adicionais de formatação incluem:

~~Texto tachado~~
`Código inline`
==Texto destacado== (alguns analisadores)
X^2^ (sobrescrito, alguns analisadores)
H~2~O (subscrito, alguns analisadores)

Note que texto destacado, sobrescrito e subscrito são extensões não suportadas por todos os analisadores Markdown. O GitHub Flavored Markdown (GFM) suporta tachado mas não destaque por padrão.

Citações em Bloco

Citações em bloco são criadas usando o símbolo maior que (>):

> Esta é uma citação em bloco.
> Ela pode abranger múltiplas linhas.

>> Citações em bloco aninhadas também são possíveis.
>> Apenas adicione mais símbolos >.

Citações em bloco são perfeitas para citações, aspas destacadas ou destacar informações importantes. Elas podem conter outras formatações Markdown, incluindo títulos, listas e blocos de código.

Linhas Horizontais

Crie quebras visuais no seu conteúdo com linhas horizontais:

---
***
___

Todas as três sintaxes produzem o mesmo resultado. Use três ou mais hífens, asteriscos ou sublinhados em sua própria linha. A maioria dos desenvolvedores prefere hífens (---) para clareza.

Escapando Caracteres Especiais

Para exibir caracteres Markdown literais, escape-os com uma barra invertida:

\*Não itálico\*
\# Não um título
\[Não um link\]

Isso é essencial quando você precisa mostrar a própria sintaxe Markdown, como em documentação ou tutoriais.

Dica profissional: Ao escrever sobre código ou tópicos técnicos, use formatação de código inline (`crases`) para nomes de funções, variáveis, caminhos de arquivo e comandos. Isso melhora a legibilidade e ajuda os leitores a distinguir código de prosa.

Links e imagens usam sintaxe similar em Markdown, tornando-os fáceis de lembrar e usar. Ambos suportam formatos inline e de estilo de referência para diferentes casos de uso.

Criando Links

A sintaxe básica de link é direta:

[Texto do link](https://example.com)
[Link com título](https://example.com "Texto ao passar o mouse")

O texto do link aparece entre colchetes, seguido imediatamente pela URL entre parênteses. O atributo de título opcional aparece entre aspas após a URL e é exibido ao passar o mouse.

Links de Estilo de Referência

Para documentos com muitos links repetidos, links de estilo de referência mantêm seu conteúdo mais limpo:

[Texto do link][id-referencia]
[Outro link][id-referencia]

[id-referencia]: https://example.com "Título opcional"

Esta abordagem separa definições de link do conteúdo, tornando o fonte mais legível. É particularmente útil em documentos longos ou quando a mesma URL aparece várias vezes.

Links Automáticos

URLs e endereços de email podem ser automaticamente convertidos em links:

<https://example.com>
<[email protected]>

Muitos analisadores Markdown também criam links automáticos de URLs simples sem colchetes angulares, mas esse comportamento não é universal. Usar colchetes angulares garante comportamento consistente entre plataformas.

Adicionando Imagens

A sintaxe de imagem é quase idêntica aos links, com um prefixo de ponto de exclamação:

![Texto alternativo](imagem.jpg)
![Texto alternativo](imagem.jpg "Título da imagem")
![Texto alternativo][referencia-imagem]

[referencia-imagem]: imagem.jpg "Título opcional"

O texto alternativo é crucial para acessibilidade e SEO. Ele descreve a imagem para leitores de tela e aparece se a imagem falhar ao carregar. Sempre forneça texto alternativo significativo que descreva o conteúdo e contexto da imagem.

Dimensionamento e Alinhamento de Imagens

O Markdown padrão não suporta dimensionamento ou alinhamento de imagens. Você precisará usar HTML para esses recursos:

<img src="imagem.jpg" alt="Texto alternativo" width="300">
<img src="imagem.jpg" alt="Texto alternativo" style="float:right;margin:10px">

A maioria dos analisadores Markdown permite HTML inline, tornando esta uma solução prática quando você precisa de mais controle sobre a apresentação da imagem.

Dica rápida: Ao vincular a páginas internas, use URLs relativas (/sobre/) em vez de URLs absolutas (https://example.com/sobre/). Isso torna seu conteúdo portável e funciona corretamente em ambientes de desenvolvimento.

Listas: Ordenadas, Não Ordenadas e Listas de Tarefas

As listas são fundamentais para organizar informações em Markdown. Elas são simples de criar e suportam aninhamento para hierarquias complexas.

Listas Não Ordenadas

Crie listas com marcadores usando asteriscos, hífens ou sinais de mais:

* Item um
* Item dois
* Item três

- Item um
- Item dois
- Item três

+ Item um
+ Item dois
+ Item três

Todos os três símbolos funcionam de forma idêntica. Escolha um e use-o consistentemente em todo o seu documento. A maioria dos desenvolvedores prefere hífens por sua clareza visual.

Listas Ordenadas

Listas numeradas usam números seguidos de pontos:

1. Primeiro item
2. Segundo item
3. Terceiro item

Aqui está um recurso útil: os números reais não importam. O Markdown renumera automaticamente sua lista quando renderizada:

1. Primeiro item
1. Segundo item
1. Terceiro item

Isso torna a reordenação de itens mais fácil, pois você não precisa renumerar tudo manualmente. No entanto, começar com 1. para cada item pode ser confuso ao ler o fonte.

Listas Aninhadas

Crie listas hierárquicas indentando itens com espaços ou tabs:

1. Primeiro item
   - Marcador aninhado
   - Outro marcador aninhado
2. Segundo item
   1. Número aninhado
   2. Outro número aninhado
      - Aninhamento ainda mais profundo

Use indentação consistente (tipicamente 2-4 espaços) para cada nível de aninhamento. A maioria dos analisadores é flexível, mas a consistência melhora a legibilidade.

Listas de Tarefas

O GitHub Flavored Markdown introduziu listas de tarefas para rastrear afazeres:

- [ ] Tarefa não marcada
- [x] Tarefa marcada
- [ ] Outra tarefa não marcada

Listas de tarefas são interativas em plataformas como GitHub—você pode marcar e desmarcar itens diretamente na visualização renderizada. Elas são perfeitas para planejamento de projetos, rastreamento de issues e documentos colaborativos.

Melhores Práticas para Listas

Código e Blocos de Código

O Markdown se destaca na exibição de código, tornando-o o formato preferido para documentação técnica e tutoriais de programação.

Código Inline

Envolva código inline com crases simples:

Use a função `console.log()` para depurar.
O elemento `<div>` é um contêiner.

A formatação de código inline preserva o espaçamento e previne interpretação Markdown. É essencial para mencionar elementos de código dentro de frases.

Blocos de Código

Crie blocos de código usando crases triplas (blocos de código cercados):

```
function hello() {
  console.log("Olá, mundo!");
}
```

Esta é a sintaxe moderna e preferida. É mais limpa e mais flexível que o método de indentação mais antigo (4 espaços ou 1 tab).

Destaque de Sintaxe

Especifique a linguagem de programação após as crases de abertura para destaque de sintaxe:

```javascript
function hello() {
  console.log("Olá, mundo!");
}
```

```python
def hello():
    print("Olá, mundo!")
```

```css
.container {
  max-width: 1200px;
  margin: 0 auto;
}
```

A maioria dos analisadores Markdown suporta dezenas de linguagens. Identificadores comuns incluem

We use cookies for analytics. By continuing, you agree to our Privacy Policy.