O Markdown que você recebe, e como limpá-lo
Última revisão
A conversão te dá um arquivo Markdown, não um documento pronto. Este é um guia de campo curto sobre o que sai, de quais partes dá para confiar e o pequeno número de edições que valem a pena antes de o arquivo entrar num repositório, num wiki ou num cofre de notas.
7 min de leitura
O que a saída realmente é
O conversor emite GitHub Flavored Markdown, o dialeto usado por GitHub, GitLab, Obsidian, importações do Notion e a maioria dos geradores de sites estáticos. É CommonMark mais alguns acréscimos, dos quais o que importa aqui são as tabelas de barras verticais.
A escolha é deliberada. O CommonMark puro não tem sintaxe de tabela nenhuma, então um conversor mirando nele ou descarta tabelas ou emite HTML cru. As tabelas do GFM se leem como texto e são entendidas em quase todo lugar onde Markdown é.
O que sobrevive à viagem
| Títulos | Sim — como #, ##, ### a partir do tamanho relativo da fonte |
|---|---|
| Parágrafos | Sim — a partir do espaçamento vertical |
| Negrito e itálico | Sim — a partir do peso e da inclinação reais da fonte |
| Listas com marcadores | Sim — a partir dos glifos de marcador iniciais |
| Listas numeradas | Sim — a partir dos numerais iniciais |
| Tabelas | As retangulares simples, como tabelas de barras GFM |
| Código em linha | Sim — a partir de trechos monoespaçados |
| Links | Sim, onde o PDF carrega uma anotação de link real |
| Imagens | Não — a saída é só texto e estrutura |
| Notas de rodapé | Como texto corrido no fim da página, sem vínculo |
| Matemática | Como os caracteres que a formam, não como LaTeX |
| Cor e fontes | Não — o Markdown não tem como expressá-las |
As cinco edições que valem sempre
Quase todo arquivo convertido precisa do mesmo pequeno conjunto de passadas. Levam alguns minutos e são a diferença entre um arquivo que dá para buscar e um que dá para ler.
- Ajuste a escada de títulos. Limiares de tamanho produzem níveis localmente certos e globalmente irregulares — um documento pode terminar com três H1 e nenhum H2. Passe os olhos só pelos títulos e renumere para que o aninhamento corresponda ao sumário real do documento.
- Rejunte parágrafos partidos. Um documento com entrelinha generosa quebra parágrafos nos fins de linha suaves. Eles se leem como uma pilha de linhas curtas; junte-as e apague as linhas em branco sobrando.
- Conserte a hifenização. Texto justificado com hífen na margem direita deixa palavras partidas entre linhas: "conver-" e depois "são". Busque no arquivo um hífen seguido de quebra de linha.
- Confira cada tabela. Conte as colunas do Markdown contra o original e confira a última linha — a linha final é a vítima mais comum. Uma tabela que perdeu a forma costuma ser mais rápida de redigitar do que de consertar.
- Apague a mobília de página. Cabeçalhos e rodapés repetidos são detectados e removidos, mas um documento que os varia — um título de capítulo diferente em cada página — pode deixar fragmentos para trás.
Uma nota sobre tabelas
Uma tabela de barras do GFM precisa do mesmo número de células em cada linha, e a linha separadora do cabeçalho decide a contagem de colunas da tabela inteira. Se o conversor contar errado uma linha, a tabela fica inválida e aparece como texto literal com barras.
É uma falha visível, o que é uma sorte: você a vê na hora em vez de descobrir depois. Uma tabela assim está quebrada:
| Região | T1 | T2 |
| --- | --- | --- |
| Norte | 120 | 140 |
| Sul | 95 |
| Leste | 88 | 102 |Como consertar
Acrescente a célula que falta, vazia se a célula de origem estava vazia. Toda linha precisa ter o mesmo número de barras que a linha separadora.
| Região | T1 | T2 |
| --- | --- | --- |
| Norte | 120 | 140 |
| Sul | 95 | |
| Leste | 88 | 102 |O escape, e por que às vezes saem contrabarras
O Markdown dá significado a caracteres que aparecem na prosa comum. Um asterisco significa ênfase, um sublinhado significa ênfase, uma cerquilha no início da linha significa título, e um número seguido de ponto no início significa item de lista.
Quando esses caracteres aparecem no seu documento como eles mesmos — uma marca de nota de rodapé, um nome de variável com sublinhados, uma linha que de fato começa com "1985." — eles precisam ser escapados com uma contrabarra, ou vão mudar em silêncio como o documento é exibido. Uma contrabarra na saída costuma ser o conversor tomando cuidado, não um erro.
Se uma contrabarra estiver atrapalhando, apagá-la é seguro desde que você confira depois como a linha aparece.
Para onde o arquivo vai depois
Markdown é texto puro, que é a razão de converter em primeiro lugar: dá para buscar com grep, comparar com diff e será legível daqui a cinquenta anos por qualquer coisa que abra um arquivo de texto.
Para um repositório, ponha no diretório e deixe a revisão de código cuidar. Para um cofre de notas, confira antes a escada de títulos, já que a maioria monta o sumário a partir dela. Para um site estático, acrescente o front matter que o seu gerador precisa — nenhum conversor consegue inventá-lo, porque ele não está no PDF. Para alimentar um modelo de linguagem, veja o guia sobre preparar PDFs para recuperação, que é outro trabalho com outras prioridades.