Por que abrir Markdown fora do editor

README que chegou por anexo, resposta de uma IA, documentação copiada de um chat, rascunho de RFC, changelog de release. Em todos esses casos você tem Markdown e quer ler, não editar. O GitHub renderiza bem, mas exige um repositório e um commit. O seu editor renderiza, mas em um painel apertado, com a fonte do código e o tema do código.

Aqui o documento vira uma página de leitura: coluna estreita, fonte com serifa, tema de sua escolha e nada de barra lateral competindo por atenção. É a diferença entre olhar um arquivo e ler um texto.

Nada do que você cola aqui sai do seu navegador. O processamento é todo local, em JavaScript, sem envio para servidor, sem log e sem armazenamento.

Os controles de leitura, e por que cada um existe

Fonte. Texto corrido em fonte monoespaçada cansa, porque toda letra ocupa a mesma largura e o olho perde a silhueta da palavra, que é o que ele usa para reconhecer o texto sem soletrar. Por isso o padrão é serifada. A monoespaçada continua ali para quando o documento é quase todo código.

Largura da coluna. Linha longa demais faz o olho errar a volta e reler a mesma frase. As três larguras oferecidas ficam entre 58 e 88 caracteres, que é a faixa onde a leitura contínua funciona melhor. Junto com o corpo do texto, em três tamanhos, dá para acertar a combinação para a sua tela e a sua distância dela.

Tema. O escuro é o padrão da casa, o claro serve para imprimir ou projetar, e o sépia baixa o contraste do branco puro, que é o que incomoda em sessão longa de leitura. O sumário lista os títulos do documento e serve de índice, e a tela cheia tira o resto da interface do caminho.

Títulos, e a estrutura que sai deles

O número de sustenidos no começo da linha define o nível: um para o título do documento, dois para seção, três para subseção, até seis. Não é decoração. É a partir dessa hierarquia que o sumário é montado, e é por ela que um leitor de tela navega o documento pulando de título em título.

Parágrafo é qualquer bloco de texto separado por uma linha em branco. Duas quebras seguidas fazem dois parágrafos; uma quebra simples, no meio de uma frase, é ignorada e o texto continua na mesma linha. Se você quer mesmo forçar a quebra sem abrir parágrafo, termine a linha com dois espaços.

# Relatório de migração

## Contexto

O banco atual roda em uma versão sem suporte desde março.

### Riscos conhecidos

Nenhum backup foi testado nos últimos seis meses.

Ênfase: negrito, itálico, riscado e código

Um asterisco de cada lado deixa em itálico, dois deixam em negrito, três fazem os dois. Sublinhado funciona igual ao asterisco para itálico e negrito, e é questão de gosto qual usar, com uma ressalva: dentro de uma palavra, o sublinhado não pega, justamente para não estragar nomes como minha_variavel_longa.

Crase simples marca código no meio da frase, e é o que você usa para um nome de arquivo, uma flag ou um trecho de comando sem tirá-lo do parágrafo. Dois tis de cada lado riscam o texto, que é uma extensão do GitHub e não faz parte do Markdown original.

Texto **em negrito**, texto *em itálico* e os dois
juntos em ***negrito e itálico***.

Rode `npm run build` antes do deploy.

Prazo ~~sexta-feira~~ segunda-feira.

Listas, inclusive a de tarefas

Hífen, asterisco ou mais no começo da linha abrem uma lista sem ordem, e tanto faz qual dos três. Número seguido de ponto abre uma lista numerada, e o número que importa é só o primeiro: os seguintes são recontados na renderização, então uma lista escrita inteira com 1. sai numerada certinho. Para aninhar, recue o item filho com dois espaços.

A lista de tarefas é a mesma lista sem ordem com um par de colchetes logo depois do marcador. Com um xis dentro, a caixa aparece marcada; vazia, desmarcada. É extensão do GitHub, e é o que transforma uma lista qualquer em checklist de pull request ou de release.

- primeiro item
- segundo item
  - item aninhado, com dois espaços de recuo
  - outro aninhado

1. subir a migração
2. rodar o smoke test
3. liberar o tráfego

- [x] backup restaurado em homologação
- [ ] janela de manutenção comunicada

Citação, linha divisória, link e imagem

Um sinal de maior no começo da linha faz citação de bloco, que serve para destacar um trecho de outra fonte, um erro copiado do log ou um aviso. Três hífens sozinhos em uma linha viram régua horizontal, que separa assuntos dentro do mesmo documento.

Link é o texto entre colchetes seguido do endereço entre parênteses. Imagem é a mesma coisa com um ponto de exclamação na frente, e o texto entre colchetes vira o atributo alt, que é o que aparece se a imagem não carregar e o que um leitor de tela anuncia. A sintaxe de imagem não está na amostra abaixo de propósito, para o manual não sair puxando arquivo de fora, mas é exatamente `!texto alternativo`.

> A migração não pode começar sem backup validado.
> Isso não é recomendação, é bloqueio.

---

Detalhes na [especificação do CommonMark](https://commonmark.org/).

Tabela, com alinhamento por coluna

A primeira linha é o cabeçalho, a segunda define o alinhamento e as demais são os dados, tudo separado por barras verticais. Os dois-pontos na linha de alinhamento é que mandam: à esquerda alinha à esquerda, dos dois lados centraliza, à direita alinha à direita. Número quase sempre fica melhor alinhado à direita.

As barras das pontas são opcionais e as colunas não precisam estar alinhadas no texto cru, embora alinhar ajude muito na hora de revisar. O número de colunas sai do cabeçalho: célula sobrando é descartada, célula faltando vira vazia.

| Método | Rota          | Status |
| :----- | :-----------: | -----: |
| GET    | /usuarios     |    200 |
| POST   | /usuarios     |    201 |
| DELETE | /usuarios/:id |    204 |

Bloco de código, com a linguagem declarada

Três crases abrem e fecham um bloco de código. O que vier logo depois das três crases de abertura é o nome da linguagem, e aparece como etiqueta no canto do bloco. Dentro do bloco nada é interpretado: asterisco continua asterisco, sustenido continua sustenido, e é por isso que o bloco é o lugar certo para colar comando, log e trecho de arquivo.

Se o próprio código tiver três crases dentro, abra o bloco com quatro. A regra é que a cerca de fechamento precisa ter pelo menos tantas crases quanto a de abertura.

```ts
export function formatarCpf(cpf: string) {
  return cpf.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4");
}
```

tsexport function formatarCpf(cpf: string) {
  return cpf.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4");
}

O que o renderizador entende, e o que ele descarta

Tudo o que está nas amostras acima, mais imagem, quebra de linha forçada e aninhamento de listas em vários níveis. É o Markdown do dia a dia, no sabor do CommonMark com as extensões do GitHub que aparecem em documentação real: tabela, lista de tarefas e riscado.

Link com esquema perigoso, como javascript:, é descartado na hora de montar o documento em vez de virar um link clicável. Isso importa porque documento Markdown circula colado de qualquer lugar, e um link que executa script é a forma mais fácil de transformar um texto em problema.

O rodapé mostra contagem de palavras e uma estimativa de tempo de leitura, calculada a partir de uma velocidade média. Serve para dimensionar o documento antes de começar, não como cronômetro.

Markdown é o formato em que a IA responde

Modelos de linguagem escrevem em Markdown por padrão. Você pede um plano de migração, uma análise comparativa, a documentação de um endpoint, e recebe títulos, listas, tabelas e blocos de código em texto cru. Enquanto está na janela do chat, aquilo é uma resposta. Colado aqui, vira um documento que você lê, ajusta e compartilha.

É especialmente útil quando a resposta é longa. Um comparativo de quinze linhas de tabela é ilegível em texto cru e óbvio renderizado, e a diferença aparece já na primeira olhada.

Perguntas frequentes

Referências

• CommonMarkA especificação que resolve as ambiguidades do Markdown original. Tem um tutorial de dez minutos que ensina a sintaxe inteira.
• GitHub Flavored MarkdownO dialeto do GitHub, que adiciona tabela, lista de tarefas e riscado ao CommonMark.
• Guia de Markdown do GitHubReferência de sintaxe em português, útil para consultar enquanto escreve.