Markdown além do básico: tabelas, footnotes e callouts

Markdown é uma das melhores decisões que o mundo de tecnologia tomou para documentação. A maioria dos devs aprende a sintaxe básica (headers, negrito, listas, blocos de código) e para aí — o que é uma pena, porque os recursos menos conhecidos são os que mais economizam tempo em documentação técnica.

Quatro recursos que uso regularmente e que valem o tempo de aprender.

Tabelas

| Algoritmo | Output (bits) | Colisão conhecida |
|-----------|---------------|-------------------|
| MD5       | 128           | Sim (2004)        |
| SHA-1     | 160           | Sim (2017)        |
| SHA-256   | 256           | Não               |

O resultado:

Alinhamento de colunas: --- é padrão, :--- alinha à esquerda, ---: à direita, :---: centralizado. Útil para tabelas de comparação, especificações de API, matrizes de decisão.

Footnotes

JWT é assinado, não criptografado.[^1] Qualquer intermediário pode ler o payload.

[^1]: A exceção são JWEs (JSON Web Encryption), que usam criptografia assimétrica, mas são raros na prática.

Footnotes são ideais para ressalvas técnicas, citações de RFC, e explicações que interromperiam o fluxo do texto principal. O número é gerado automaticamente — você define o rótulo, não o número.

Suporte varia por parser. GitHub Flavored Markdown suporta. CommonMark puro não — depende de extensão.

Definição de links por referência

Em vez de repetir URLs longas inline:

O [Quick Tools][qt] é um conjunto de ferramentas para devs.
Veja o [editor Markdown][md] e o [gerador de UUID][uuid].

[qt]: https://quickeasy.tools
[md]: /pt/tools/markdown-editor
[uuid]: /pt/tools/uuid-generator

Isso deixa o texto mais legível e facilita atualizar URLs — você muda em um lugar e todos os links que usam o rótulo atualizam. Útil em READMEs grandes com muitos links para a mesma documentação.

Blocos de código com destaque de linha

Alguns renderers (incluindo o Editor Markdown do Quick Tools) suportam destaque de linhas específicas:

```javascript {2,4-5}
function decodeJwt(token) {
  const [h, p] = token.split('.');  // linha 2 em destaque
  return {
    header:  JSON.parse(atob(h)),   // linhas 4-5 em destaque
    payload: JSON.parse(atob(p)),
  };
}
```

Isso é particularmente útil em tutoriais onde você quer chamar atenção para as linhas que mudaram entre um snippet e outro.

O que vale saber sobre compatibilidade

Markdown não tem um padrão único. CommonMark define o comportamento base, mas tabelas (GFM), footnotes e destaque de linhas são extensões. Verifique o que seu renderer suporta antes de depender dessas features em produção.

Para documentação que vai para GitHub: GFM (GitHub Flavored Markdown) suporta tabelas e — desde 2021 — footnotes. Para documentação que vai para um site com markdown customizado, verifique a lista de extensões do seu processador.

Padrões que deixam Markdown mais sustentável

Markdown funciona melhor quando o time combina algumas regras simples. Use um único H1 por documento, que geralmente é o título. Separe seções com H2, use H3 apenas quando houver uma hierarquia real e evite pular níveis. Isso melhora leitura, TOC automático e acessibilidade.

Para blocos de código, sempre informe a linguagem. Isso melhora highlight, revisão e cópia. Para tabelas, mantenha colunas curtas; se a tabela precisar de parágrafos longos, provavelmente uma lista ou seção é mais legível.

Checklist antes de publicar

Verifique links relativos, imagens quebradas, headings duplicados e listas muito longas. Depois renderize o Markdown no mesmo componente usado em produção, porque GitHub, docs internas e site público nem sempre tratam extensões da mesma forma.

O Markdown Editor ajuda a validar a prévia antes de publicar. Use-o também para testar trechos com tabelas, listas aninhadas e blocos de código que costumam quebrar em renderizadores diferentes.

Convenções que evitam surpresa

Padronize extensões, plugins e regras de lint para Markdown antes de o conteúdo crescer. Se cada pessoa escreve tabelas, anchors e blocos de código de um jeito diferente, a manutenção fica cara. Um guia curto com exemplos aprovados costuma resolver mais do que uma documentação longa que ninguém consulta.

Manutenção de longo prazo

Revise documentos Markdown importantes quando a estrutura do site mudar. Links internos, âncoras e exemplos de código envelhecem rápido. Uma revisão pequena a cada release evita que a documentação continue indexada, mas deixe de responder ao problema atual do usuário.