O Markdown é onipresente: em arquivos README, issues do GitHub, sites de documentação, mensagens do Slack, posts de blog e, sim, até mesmo neste artigo. Criado por John Gruber em 2004, o Markdown é uma linguagem de marcação leve que transforma texto puro em HTML formatado. Se você escreve código, você escreve Markdown — portanto, é fundamental escrevê-lo de forma eficaz e profissional.

Sintaxe Essencial

Títulos (Headings)

Títulos em Markdown
# Título Principal (H1 — use apenas um por documento)
## Seção Principal (H2 — para divisões importantes)
### Subseção (H3 — para detalhamento)
#### Subsubseção (H4 — raramente necessário)

Formatação de Texto

Negrito, Itálico, Tachado
**texto em negrito**
*texto em itálico*
***texto em negrito e itálico***
~~texto tachado~~
`código inline`

Listas

Listas Ordenadas e Não Ordenadas
- Item não ordenado 1
- Item não ordenado 2
  - Item aninhado (2 espaços de indentação)
  - Outro item aninhado

1. Item ordenado 1
2. Item ordenado 2
3. Item ordenado 3

- [x] Tarefa concluída (GitHub)
- [ ] Tarefa pendente

Links e Imagens

Links & Imagens
[Texto do Link](https://exemplo.com)
[Link com Título](https://exemplo.com "Título exibido ao passar o mouse")
![Texto Alternativo da Imagem](https://exemplo.com/imagem.png)


[Clique aqui][documentacao]
[Outro link][documentacao]

[documentacao]: https://docs.exemplo.com

Blocos de Código

Blocos de Código
Código inline: `const valor = 42;`

Bloco de código delimitado com destaque de sintaxe:
```javascript
function saudar(nome) {
  return `Olá, ${nome}!`;
}
```

```bash
npm install express
npm run dev
```

Tabelas

Tabelas em Markdown
| Recurso    | Chrome | Firefox | Safari |
|------------|:------:|:-------:|:------:|
| WebP       | ✅     | ✅      | ✅     |
| AVIF       | ✅     | ✅      | ✅     |
| JPEG XL    | ❌     | ❌      | ✅     |

Alinhamento:
| Esquerda  | Centro | Direita |
|:----------|:------:|--------:|
| Conteúdo  | Centro | Direita |

Citações em Bloco (Blockquotes)

Citações em Bloco
> Esta é uma citação em bloco.
> Ela pode abranger várias linhas.
>
> — Nome do Autor

Markdown Flavored GitHub (GFM)

O GitHub expande o Markdown padrão com recursos úteis:

  • Listas de Tarefas: - [x] Concluído / - [ ] A Fazer
  • URLs Auto-linkáveis: Basta colar uma URL e ela se torna clicável
  • Emojis: :rocket: → 🚀, :bug: → 🐛
  • Alertas: > [!NOTE], > [!WARNING], > [!CAUTION]
  • Destaque de Sintaxe: Blocos de código delimitados com identificadores de linguagem
  • Notas de Rodapé: Texto[^1] e [^1]: Conteúdo da nota de rodapé

Criando um README Excepcional

Modelo de README
# Nome do Projeto

Breve descrição do que este projeto faz.

## Instalação

```bash
npm install meu-pacote
```

## Uso

```javascript
import { funcao } from 'meu-pacote';
funcao.executarAlgo();
```

## Referência da API

### `executarAlgo(opcoes)`

| Parâmetro | Tipo   | Padrão | Descrição       |
|-----------|--------|--------|-------------------|
| `timeout` | number | 5000   | Timeout em ms     |
| `retries` | number | 3      | Número de tentativas |

## Contribuição

1. Faça um fork do repositório
2. Crie sua branch (`git checkout -b feature/incrivel`)
3. Commite suas alterações
4. Abra um Pull Request

## Licença

MIT

Melhores Práticas

  • Um H1 por documento — use H2 e H3 para seções
  • Deixe linhas em branco antes e depois de títulos, listas e blocos de código
  • Utilize links estilo referência para URLs longas ou repetidas
  • Adicione identificadores de linguagem aos blocos de código para realce de sintaxe
  • Mantenha as linhas com menos de 80-100 caracteres para melhor legibilidade em texto puro
  • Use texto alternativo (alt text) para imagens — não apenas para acessibilidade, mas também para quando as imagens não carregarem

Experimente Nossas Ferramentas Gratuitas para Desenvolvedores

Formate e codifique o conteúdo da sua documentação.