Guia Completo de Markdown: Sintaxe, Dicas e Melhores Práticas

· 12 min de leitura

Índice

O Que É Markdown?

Markdown é uma linguagem de marcação leve criada por John Gruber em colaboração com Aaron Swartz em 2004. Ela permite escrever texto formatado usando sintaxe de texto simples que permanece legível mesmo sem renderização. Em vez de clicar em botões em um processador de texto ou escrever tags HTML verbosas, você usa caracteres simples e intuitivos como # para títulos, ** para texto em negrito e - para listas.

A filosofia por trás do Markdown é elegantemente simples: o texto fonte deve ser tão legível quanto a saída renderizada. Quando você abre um arquivo Markdown em qualquer editor de texto, pode entender imediatamente sua estrutura e conteúdo sem precisar de software especial ou mecanismos de renderização.

Markdown se tornou o padrão de fato para escrita técnica, documentação, arquivos README, posts de blog e anotações em todo o mundo do desenvolvimento de software. Grandes plataformas como GitHub, GitLab, Reddit, Stack Overflow, Discord, Slack, Notion e Obsidian suportam Markdown nativamente, tornando-o uma habilidade essencial para desenvolvedores, redatores técnicos e criadores de conteúdo.

Por Que Usar Markdown?

Dica profissional: Se você trabalha regularmente com arquivos Markdown, experimente nosso Editor de Markdown para visualização ao vivo e destaque de sintaxe, ou use o Conversor de Markdown para HTML para transformar seus documentos instantaneamente.

Títulos e Estrutura do Documento

Títulos são a espinha dorsal da estrutura do documento em Markdown. Eles usam o símbolo #, onde o número de símbolos de cerquilha determina o nível do título de 1 a 6:

# Título 1
## Título 2
### Título 3
#### Título 4
##### Título 5
###### Título 6

Sempre inclua um espaço após o símbolo #—a maioria dos processadores Markdown o exige, e melhora a legibilidade. A saída renderizada cria tags de título HTML adequadas (<h1> até <h6>), que são cruciais para estrutura do documento, acessibilidade e SEO.

Melhores Práticas para Títulos

Use níveis de título sequencialmente sem pular níveis. Não pule de H1 para H3—isso quebra a hierarquia do documento e cria problemas de acessibilidade para usuários de leitores de tela. Pense nos títulos como um esboço: cada nível deve aninhar logicamente dentro do anterior.

A maioria dos documentos deve ter apenas um título H1 (o título), com títulos H2 para seções principais e H3-H6 para subseções. Isso cria uma hierarquia de informações clara que tanto humanos quanto mecanismos de busca podem entender.

Dica rápida: Muitos processadores Markdown geram automaticamente links âncora para títulos, permitindo que você vincule diretamente a seções específicas. O GitHub, por exemplo, converte "## Começando" em uma âncora que você pode referenciar com #começando.

Sintaxe Alternativa de Títulos

Markdown também suporta uma sintaxe alternativa para títulos H1 e H2 usando sublinhados:

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

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

Embora essa sintaxe seja válida, a sintaxe de cerquilha é mais comum e suporta todos os seis níveis de título, tornando-a a escolha preferida para a maioria dos escritores.

Fundamentos de Formatação de Texto

Markdown fornece sintaxe simples e 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.

Formato Sintaxe Alternativa Resultado
Negrito **negrito** __negrito__ negrito
Itálico *itálico* _itálico_ itálico
Negrito + Itálico ***ambos*** ___ambos___ ambos
Tachado ~~deletado~~ — deletado
Código inline `código` — código
Subscrito H~2~O — H2O
Sobrescrito X^2^ — X2
Destacado ==marcado== — marcado

Detalhes da Sintaxe de Ênfase

Tanto asteriscos (*) quanto sublinhados (_) funcionam para ênfase, mas asteriscos são mais comumente usados e recomendados. A diferença chave: asteriscos funcionam no meio da palavra (in*droga*crível), enquanto sublinhados requerem limites de palavra.

Para texto em negrito, use asteriscos ou sublinhados duplos. Para texto em itálico, use asteriscos ou sublinhados simples. Combine três para texto em negrito itálico. Essa consistência torna sua fonte Markdown mais legível e previsível.

Dica profissional: Ao escrever documentação técnica, use `crases` para código inline, nomes de funções, caminhos de arquivo e argumentos de linha de comando. Essa distinção visual ajuda os leitores a identificar rapidamente elementos de código dentro da prosa.

Escapando Caracteres Especiais

Se você precisar exibir asteriscos literais, sublinhados ou outros caracteres de sintaxe Markdown, escape-os com uma barra invertida:

Isso \*não é itálico\* e \*\*não é negrito\*\*
Use \# para mostrar uma cerquilha sem criar um título

Caracteres comuns que precisam de escape incluem: \ ` * _ { } [ ] ( ) # + - . !

Listas: Ordenadas, Não Ordenadas e Aninhadas

Listas são fundamentais para organizar informações em Markdown. Elas são simples de criar e suportam aninhamento para conteúdo hierárquico.

Listas Não Ordenadas

Crie listas não ordenadas (com marcadores) usando -, * ou + seguido de um espaço. Todos os três marcadores funcionam de forma idêntica, mas a consistência dentro de um documento melhora a legibilidade:

- Primeiro item
- Segundo item
- Terceiro item
  - Item aninhado (indente com 2 espaços)
  - Outro item aninhado
- Quarto item

A indentação padrão para listas aninhadas é de dois espaços, embora alguns analisadores aceitem quatro. Mantenha dois espaços para máxima compatibilidade.

Listas Ordenadas

Listas ordenadas (numeradas) usam números seguidos de pontos e um espaço:

1. Primeiro passo
2. Segundo passo
3. Terceiro passo
   1. Sub-passo A
   2. Sub-passo B
4. Quarto passo

Aqui está um recurso útil: os números reais que você usa não importam. Markdown renumera automaticamente as listas sequencialmente quando renderizadas. Você pode usar 1. para cada item, facilitando a reordenação de itens sem renumeração:

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

Isso renderiza como uma lista numerada adequadamente 1, 2, 3. Essa técnica é particularmente útil ao manter listas longas ou reordenar itens com frequência.

Listas de Tarefas

Muitos sabores de Markdown (incluindo GitHub Flavored Markdown) suportam listas de tarefas com caixas de seleção:

- [x] Tarefa concluída
- [ ] Tarefa incompleta
- [ ] Outra tarefa incompleta

Listas de tarefas são inestimáveis para gerenciamento de projetos, rastreamento de problemas e listas de afazeres em documentação.

Dica rápida: Para incluir múltiplos parágrafos ou blocos de código dentro de um item de lista, indente o conteúdo subsequente para alinhar com o primeiro caractere do texto do item da lista (tipicamente 3-4 espaços para listas não ordenadas, 4 espaços para listas ordenadas).

Listas de Definição

Algumas sintaxes Markdown estendidas suportam listas de definição para glossários e definições de termos:

Termo 1
: Definição para termo 1

Termo 2
: Primeira definição para termo 2
: Segunda definição para termo 2

Embora não seja universalmente suportado, listas de definição são úteis para documentação técnica e glossários.

Markdown facilita adicionar hiperlinks e imagens mantendo o texto fonte legível.

Links Inline

A sintaxe de link mais comum usa colchetes para o texto do link e parênteses para a URL:

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

O texto de título opcional aparece como uma dica de ferramenta quando os usuários passam o mouse sobre o link. Isso é útil para fornecer contexto adicional sem sobrecarregar o texto do link visível.

Links Estilo Referência

Para documentos com muitos links ou URLs repetidas, links estilo referência melhoram a legibilidade:

Este é [um link][1] e aqui está [outro link][2].

[1]: https://example.com
[2]: https://example.com/page "Título opcional"

Você também pode usar referências descritivas em vez de números:

Confira o [Google][google] e o [GitHub][gh].

[google]: https://google.com
[gh]: https://github.com

Definições de referência podem aparecer em qualquer lugar do documento e não serão renderizadas na saída. Muitos escritores as colocam no final das seções ou no final do documento.

Links Automáticos

Envolva URLs ou endereços de e-mail em colchetes angulares para criar links automáticos:

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

A maioria dos analisadores Markdown modernos também converte automaticamente URLs simples em links clicáveis, embora esse comportamento não seja garantido em todas as plataformas.

Imagens

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

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

O texto alternativo é crucial para acessibilidade—ele descreve a imagem para usuários de leitores de tela e é exibido quando a imagem falha ao carregar. Sempre forneça texto alternativo significativo que transmita o conteúdo e propósito da imagem.

A sintaxe estilo referência também funciona para imagens:

![Logo][logo]

[logo]: /images/logo.png "Logo da empresa"

Dica profissional: Markdown padrão não suporta dimensionamento ou alinhamento de imagem. Para esses recursos, você precisará usar HTML diretamente: <img src="imagem.jpg" width="300" alt="Descrição"> ou confiar em sintaxe Markdown estendida específica da sua plataforma.

Vinculando Imagens

Para tornar uma imagem clicável, envolva a sintaxe da imagem na sintaxe do link:

[![Texto alternativo](miniatura.jpg)](tamanho-completo.jpg)

Essa técnica é comumente usada para galerias de imagens ou vinculação de miniaturas a versões em resolução completa.

Blocos de Código e Destaque de Sintaxe

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

Para trechos curtos de código dentro do texto, use crases simples:

Use a função `print()` para exibir saída.
O arquivo `config.json` contém configurações.

Se seu código contém crases, use crases duplas para envolvê-lo:

``Use `crases` no código``

Blocos de Código Cercados

Para blocos de código de múltiplas linhas, use três crases (```) ou três tils (~~~) antes e depois do código:

```
function greet(name) {
  return `Hello, ${name}!`;
}
```

Isso cria um bloco de código adequadamente formatado com fonte monoespaçada e espaço em branco preservado.

Destaque de Sintaxe

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

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
#!/bin/bash
echo "Olá, Mundo!"
```