Markdown: Referência Completa de Sintaxe para Escritores e Desenvolvedores

Markdown está em todo lugar. É o formato de escrita padrão no GitHub, a espinha dorsal da maioria dos geradores de sites estáticos, a linguagem nativa de ferramentas como Obsidian e Notion, e o formato que os desenvolvedores usam para escrever READMEs, documentação e notas técnicas. Apesar de ser onipresente, muitos escritores e desenvolvedores aprendem apenas o básico — negrito, itálico e alguns níveis de cabeçalho — e perdem os recursos que tornam o Markdown genuinamente poderoso para escrita estruturada.

Você pode escrever e pré-visualizar Markdown instantaneamente usando o Editor de Markdown do BrowseryTools — gratuito, sem cadastro, tudo fica no seu navegador.

Quem Criou o Markdown e Por quê

O Markdown foi criado por John Gruber, em colaboração com Aaron Swartz, e lançado em 2004. O objetivo declarado de Gruber era criar um formato de escrita em texto simples que fosse legível como está — antes de qualquer renderização — e que convertesse de forma limpa para HTML válido. O nome é uma brincadeira com "linguagem de marcação" (HTML é HyperText Markup Language), invertendo o conceito: em vez de adicionar sintaxe para controlar a formatação, o Markdown usa os hábitos naturais de pontuação que as pessoas já haviam desenvolvido em e-mails de texto simples.

A motivação era prática. HTML é verboso e distrai ao escrever inline. Uma frase como <p>Este é um texto <strong>importante</strong>.</p> requer uma sobrecarga mental significativa em comparação com Este é um texto **importante**. Gruber queria que blogueiros e escritores se concentrassem nas palavras, não nas tags. A especificação original do Markdown era um script Perl que convertia arquivos Markdown em texto simples para HTML.

Sintaxe Básica

A sintaxe central do Markdown cobre tudo que a maioria dos escritores precisa para documentos estruturados.

Títulos

Use sinais de hash para criar títulos. Um hash para H1, dois para H2, até seis para H6. A maioria dos guias de estilo recomenda apenas um H1 por documento (tipicamente o título) e usar H2–H4 para hierarquia de conteúdo.

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

Ênfase e Negrito

*itálico* ou _itálico_
**negrito** ou __negrito__
***negrito e itálico***
~~tachado~~

Links e Imagens

[Texto do link](https://example.com)
[Link com título](https://example.com "Título da página")
![Texto alternativo](image.png)
![Texto alternativo](image.png "Título da imagem")

Listas

Listas não ordenadas usam hífens, asteriscos ou sinais de mais. Listas ordenadas usam números seguidos de pontos. Itens recuados (2 ou 4 espaços) criam listas aninhadas.

- Item não ordenado
- Outro item
  - Item aninhado

1. Primeiro
2. Segundo
3. Terceiro

Código

Código inline usa crases simples. Blocos de código delimitados usam três crases com um identificador opcional de linguagem para realce de sintaxe.

Use `console.log()` para depurar.

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

Citações em Bloco

> Isso é uma citação em bloco.
> Pode abranger múltiplas linhas.
>
> > Citações em bloco aninhadas também funcionam.

Réguas Horizontais

Três ou mais hífens, asteriscos ou sublinhados em uma linha por si mesmos criam uma régua horizontal. --- é a convenção mais comum.

Sintaxe Estendida

A especificação original do Markdown deixou de fora vários recursos que os escritores comumente precisam. A sintaxe estendida, suportada pela maioria dos processadores modernos, adiciona essas capacidades.

Tabelas

| Coluna 1  | Coluna 2  | Coluna 3  |
|-----------|:---------:|----------:|
| Esquerda  | Centro    | Direita   |
| alinhada  | alinhada  | alinhada  |

A posição dos dois-pontos na linha separadora controla o alinhamento: à esquerda (padrão), centralizado (dois-pontos nos dois lados) ou à direita (dois-pontos à direita).

Listas de Tarefas

- [x] Escrever primeiro rascunho
- [x] Revisão por pares
- [ ] Edições finais
- [ ] Publicar

Notas de Rodapé

Aqui está uma afirmação que precisa de citação.[^1]

[^1]: A fonte de suporte ou explicação vai aqui.

Variantes de Markdown: CommonMark, GFM e MDX

A especificação original do Markdown tinha ambiguidades — lugares onde os processadores tomavam decisões diferentes sobre casos extremos. Isso levou a implementações incompatíveis entre diferentes ferramentas. Vários esforços de padronização surgiram para resolver isso.

• CommonMark — uma especificação rigorosa que resolve toda ambiguidade na especificação original do Markdown com um conjunto formal de testes. Adotado pelo Discourse, Reddit, Stack Overflow e muitos outros. A variante mais interoperável.
• GitHub Flavored Markdown (GFM) — a extensão do CommonMark pelo GitHub que adiciona tabelas, listas de tarefas, tachado, autolinks e URLs literais. Se você escreve arquivos README ou comentários no GitHub, está usando GFM.
• MDX — Markdown estendido com suporte a componentes JSX, usado extensivamente em sites de documentação baseados em React (docs do Next.js, Docusaurus, Astro). Permite importar e incorporar componentes React diretamente em arquivos Markdown.
• MultiMarkdown / Pandoc Markdown — extensões ricas em recursos para escrita acadêmica, com suporte para citações, equações matemáticas (LaTeX) e formatação complexa de tabelas.

Onde o Markdown É Usado

• GitHub e GitLab — arquivos README, issues, pull requests, wikis e comentários todos renderizam Markdown
• Notion — suporta importação/exportação de Markdown e um subconjunto de atalhos Markdown para formatação inline
• Obsidian — um aplicativo de gerenciamento de conhecimento construído inteiramente em arquivos Markdown com extensões de wikilink
• Geradores de sites estáticos — Jekyll, Hugo, Gatsby, Astro e Next.js todos usam Markdown ou MDX como formato de conteúdo padrão
• Plataformas de documentação — ReadTheDocs, GitBook e Docusaurus são construídos em torno de Markdown
• Plataformas de chat — Slack, Discord e Teams suportam subconjuntos de Markdown para formatação de mensagens
• Clientes de e-mail — alguns clientes (Superhuman, HEY) suportam entrada em Markdown

Markdown vs Editores de Texto Rico

Editores de texto rico (WYSIWYG — O que você vê é o que você obtém) como Google Docs, Microsoft Word ou o editor embutido do Contentful mostram a saída formatada enquanto você digita. O Markdown mostra o código-fonte bruto. Os trade-offs são reais.

• Vantagens do Markdown — arquivos de texto simples, funciona em qualquer editor, controlável com git, sem dependência de fornecedor, fluxo de trabalho rápido apenas com teclado
• Vantagens do texto rico — imediatamente visual, sem sintaxe para aprender, mais fácil para colaboradores não técnicos, melhor para formatação complexa (notas de rodapé, comentários, rastreamento de alterações)

Para escrita técnica, documentação de desenvolvedores e gerenciamento pessoal de conhecimento, a portabilidade do Markdown e a compatibilidade com controle de versão o tornam a melhor escolha. Para documentos de negócios colaborativos ou conteúdo com requisitos de formatação complexos, um editor de texto rico frequentemente é mais prático.

Erros Comuns no Markdown

• Linhas em branco ausentes — a maioria dos elementos de bloco (títulos, listas, blocos de código) requer uma linha em branco antes e depois para renderizar corretamente
• Espaços após sinais de hash — ##Título sem espaço após os hashes não é um título na maioria dos processadores
• Marcadores de lista inconsistentes — misturar - e * na mesma lista pode produzir resultados inesperados em alguns processadores
• Esquecer de escapar caracteres especiais — asteriscos, sublinhados e crases dentro do texto precisam de um escape com barra invertida se devem ser renderizados literalmente
• Assumir que a sintaxe estendida é universal — tabelas e listas de tarefas são recursos do GFM não suportados por todos os processadores; verifique seu ambiente alvo

O Editor de Markdown do BrowseryTools fornece uma pré-visualização ao vivo para que você possa detectar problemas de renderização imediatamente enquanto escreve, sem copiar o texto para outra ferramenta. Cole seu Markdown e veja a saída HTML renderizada lado a lado.