Por que escrever em Markdown
Markdown é uma linguagem de marcação leve que usa símbolos simples para representar formatação. Quem escreve não precisa tocar no mouse, foca no conteúdo e a formatação é gerada automaticamente.
Vantagens:
- Texto puro, qualquer editor consegue abrir
- Amigável a controle de versão (Git consegue fazer diff)
- Conversível para HTML, PDF, Word e outros formatos
- Baixo custo de aprendizado, iniciação em 10 minutos
Sintaxe básica
Títulos
# Título nível 1
## Título nível 2
### Título nível 3
#### Título nível 4
Recomenda-se apenas um título de nível 1 por artigo.
Parágrafos
Linhas em branco separam parágrafos. Conteúdo sem linha em branco é considerado o mesmo parágrafo.
Ênfase
**negrito**
*itálico*
~~tachado~~
Listas
Não ordenadas:
- item
- item
- subitem (indentado)
Ordenadas:
1. Primeiro item
2. Segundo item
Links e imagens
[texto do link](https://example.com)
Código
Em linha: código
Bloco de código:
```javascript
const x = 1;
### Citação
conteúdo citado segunda linha
### Linha divisória
## Sintaxe estendida
### Tabelas
| Nome | Idade |
|---|---|
| Tom | 25 |
### Lista de tarefas
- Concluído
- Não concluído
### Notas de rodapé
Texto do corpo[^1]
[^1]: Explicação da nota de rodapé
### Tachado
tachado
### Link automático
URL vira link automaticamente.
## Técnicas de escrita
### Hierarquia de títulos clara
- Título nível 1: título do artigo
- Título nível 2: seções principais
- Título nível 3: subseções
- Não pular níveis (do nível 1 direto para o nível 3)
### Parágrafos concisos
- Um parágrafo, uma ideia
- Parágrafos não muito longos (3-5 linhas é o ideal)
- Use listas no lugar de parágrafos longos
### Use listas com bom senso
Conteúdo paralelo usa listas, mais claro que parágrafos:
- Passos usam listas ordenadas
- Itens paralelos usam listas não ordenadas
- Comparações usam tabelas
### Marque a linguagem nos blocos de código
Marque a linguagem no bloco de código para acionar o realce de sintaxe:
Adicione descrição às imagens
A descrição em  é importante:
- Exibida quando a imagem não carrega
- Leitores de tela leem a descrição para usuários com deficiência visual
- Favorável ao SEO
Links claros
- O texto do link descreve o conteúdo de destino, não use "clique aqui"
- Links externos usam URL completa
- Links internos usam caminho relativo
Organização de documentos
Coloque um sumário no início
Documentos longos devem ter um sumário no início, com links para cada seção. Facilita a navegação.
Separe seções com títulos
Use títulos para separar seções, não linhas divisórias. Títulos têm hierarquia, linhas divisórias não.
Separe código e texto
Deixe uma linha em branco antes e depois dos blocos de código, separando-os do texto. Leitura mais clara.
Posicione imagens adequadamente
Imagens devem ficar próximas ao texto relacionado, não concentradas no final. Leitores que leem em sequência conseguem ver a imagem a tempo.
Escolha do editor
VS Code
- Gratuito e poderoso
- Instale extensões Markdown (como Markdown All in One)
- Pré-visualização em tempo real
- Adequado para desenvolvedores
Typora
- WYSIWYG (o que você vê é o que você obtém)
- Sem janela de pré-visualização, edita diretamente o resultado renderizado
- Pago, mas barato
- Adequado para escrita focada
Obsidian
- Base de conhecimento local
- Links bidirecionais
- Rico em extensões
- Adequado para notas e gestão de conhecimento
Editores online
- StackEdit: editor Markdown online
- Jian Shu: plataforma de escrita em chinês
- Adequado para escrita temporária
Markdown para HTML
Após escrever em Markdown, para exibir em uma página web, converta para HTML. Use a ferramenta Markdown para HTML para conversão em um clique.
Erros comuns
Sem espaço após o título
#título não é reconhecido, use # título (espaço após #).
Indentação de lista incorreta
Sublistas devem ser indentadas 2 ou 4 espaços (depende do analisador). Indentação incorreta faz a sublista não aparecer.
Bloco de código não fechado
### Caracteres especiais não escapados
Para exibir símbolos como * e #, adicione \ antes para escapar: \* exibe *.
### Erro de sintaxe de tabela
Tabelas precisam de uma linha separadora de cabeçalho (| --- |). Sem ela, não são reconhecidas como tabela.
### Parênteses do link não casam
`[link](url` sem o parêntese de fechamento, o link não é reconhecido.
## Melhores práticas
### Um documento, um tema
Um artigo deve abordar um tema. Vários temas devem ser divididos em vários artigos, relacionados por links.
### Escreva o conteúdo primeiro, ajuste a formatação depois
Escreva o texto puro primeiro, depois adicione a marcação Markdown. Evite ajustar enquanto escreve, o que interrompe o raciocínio.
### Padronize o estilo
Equipes de escrita devem padronizar o estilo:
- Quantos níveis de título usar
- Listas com - ou *
- Marcação de linguagem nos blocos de código
- Quantos níveis de aninhamento de lista no máximo
### Preserve o arquivo fonte
Markdown é o arquivo fonte, HTML/PDF são produtos gerados. Preserve o Markdown para facilitar alterações, regerando os formatos de saída a cada vez.
## Resumo
O essencial da escrita em Markdown: hierarquia de títulos clara, parágrafos concisos, bom uso de listas, marcação de linguagem no código, descrição nas imagens. Escolha um editor adequado, padronize o estilo e preserve o arquivo fonte. Para exibição, use a [ferramenta Markdown para HTML do DocsAll](/convert-tools/markdown-to-html), que roda no navegador.