Gerador de Sumário Markdown

Gerador de Sumário Markdown

Analisa qualquer documento Markdown e emite um Sumário navegável — formatado exatamente como o GitHub, GitLab ou seu gerador de site estático esperam. Configure quais níveis incluir, escolha o estilo de bullet, indentação e como os slugs de âncora são gerados. A saída é Markdown puro para colar no topo do README, ou deixar a ferramenta injetar no lugar de um placeholder [TOC] / <!-- toc -->. Todo o processamento é no navegador; o documento nunca sai do dispositivo.

O que é um Sumário Markdown e onde é usado?

Um sumário Markdown é uma lista de links que apontam para os headings dentro do mesmo documento. Quando o documento é renderizado em GitHub, GitLab, GitBook, MkDocs, Docusaurus, Jekyll, Hugo, Notion, Obsidian ou qualquer visualizador Markdown que adiciona âncoras aos headings, o sumário vira um mapa navegável da página.

Leitores passam o olho pelo sumário para achar o que precisam sem rolar. Mantenedores usam o sumário como ferramenta de revisão estrutural — um olhar revela se a hierarquia faz sentido.

Lugares comuns para embutir um sumário:

- Topo de um README.md longo, logo após a descrição do projeto.
- Acima da seção API em documentação técnica.
- Em um ADR (architecture decision record) quando há várias alternativas.
- Em atas de reunião ou design docs com muitas seções.

Como o parser detecta headings?

O parser lida com os dois estilos de heading que o Markdown suporta:

1. ATX: 1–6 # no início da linha, seguido por espaço e o texto. # finais opcionais são removidos.

# Título H1
## Seção H2
### Subseção H3

2. Setext: o texto em uma linha e uma linha de = (H1) ou - (H2) abaixo. O estilo setext é mais antigo e menos comum, mas é Markdown válido.

Quando 'Ignorar blocos de código' está ligado (padrão), o parser rastreia blocos com cerca (``` e ~~~) e blocos indentados (4 espaços) e pula linhas que parecem headings dentro deles. Isso evita que 'parece código Python: # comentário' seja confundido com heading.

Texto após # sem espaço (`#hashtag`) não é heading, conforme CommonMark. Headings indentados com mais de 3 espaços também não são reconhecidos como ATX — são texto de parágrafo.

Qual a diferença entre os estilos de slug?

Diferentes renderizadores Markdown convertem texto de heading em ID de âncora de jeitos um pouco diferentes. Escolha o estilo do destino:

- GitHub: minúsculas, espaços viram hífens, pontuação removida, letras Unicode preservadas. 'Introduction!' → introduction; 'API V2.0' → api-v20. Padrão de fato no GitHub, gists, GitLab, view Markdown do Notion e muitos geradores estáticos (Eleventy, Astro).

- GitLab: similar ao GitHub mas permite underscores. 'two_words and three' → two_words-and-three.

- CommonMark / Pandoc: ASCII estrito, remove dígitos e pontuação iniciais. '1. Background' → background. Use para Pandoc ou renderizadores CommonMark estritos.

- Texto simples (sem links): só o texto sem âncora. Útil quando o destino não suporta âncoras (alguns apps de chat, email em texto plano).

Como funciona a deduplicação de âncoras?

Quando dois headings têm o mesmo texto, os slugs colidem e só o primeiro link funciona. A ferramenta rastreia todos os slugs emitidos no sumário atual e adiciona `-1`, `-2`, etc. aos duplicados:

## Exemplos
### Setup → setup
## Outro Tópico
### Setup → setup-1
### Setup → setup-2

Isso corresponde ao comportamento real do GitHub para headings repetidos. GitLab usa o mesmo padrão. Pandoc descarta o duplicado a menos que você ative o mesmo esquema via `pandoc --slugify`.

Se você muda a fonte e regenera, os sufixos são reatribuídos na nova ordem. Salve o arquivo com o sumário inserido se quiser URLs estáveis entre execuções.

Por que a ferramenta às vezes pula o H1?

O Nível Mínimo padrão é H2. É a convenção mais comum em Markdown — o primeiro H1 é o próprio título do documento, e o sumário descreve as seções dentro desse título.

Você repetiria o título incluindo H1 no sumário, então a maioria dos projetos começa o sumário em H2.

Se seu documento usa H1 para seções (sem título de nível superior), defina o Nível Mínimo como H1.

O Nível Máximo controla a profundidade. H2–H3 dá visão plana. H2–H4 adiciona o subnível. H2–H6 dá hierarquia completa — útil para documentação técnica longa mas pode poluir.

O que 'Inserir na fonte' faz?

Três comportamentos dependendo da fonte:

1. Se o documento contém um placeholder [TOC], substitui. Convenção Pandoc / Python-Markdown / WordPress.
2. Se contém um comentário HTML <!-- toc -->, substitui. Convenção doctoc / markdown-toc-cli.
3. Caso contrário, insere o sumário logo após o primeiro H1 (ou no topo se não houver), separado por linhas em branco.

É execução manual — a ferramenta não rastreia o documento nem atualiza o sumário automaticamente quando você edita headings. Para manutenção automatizada, use doctoc (pacote npm) ou um pre-commit hook que execute essa lógica ao salvar.

O sumário inserido é Markdown puro — sem wrapper HTML a menos que você marque 'Envolver com heading', que adiciona uma linha `## Sumário` acima da lista.

Funciona com headings que não estão em inglês?

Sim. Os geradores de slug preservam letras e dígitos Unicode — 'Câu hỏi thường gặp', 'Préférences', 'Configuración', '常见问题' produzem slugs válidos compatíveis com GitHub.

O GitHub mantém os caracteres Unicode no slug; o fragmento da URL os terá codificados como bytes %XX quando o link for seguido. Navegadores lidam com isso de forma transparente.

Se trocar para CommonMark, as regras são mais estritas — letras Unicode fora de [a-z0-9] são removidas. Para documentos multilíngues em GitHub, GitLab ou Notion, prefira GitHub ou GitLab.

Texto bidirecional (árabe, hebraico) funciona tanto no texto visível quanto no slug. O sumário lê esquerda-para-direita na fonte mas renderiza correto em navegadores que tratam bidi.

O que a Verificação de Âncoras reporta?

A verificação é um linter pré-publicação que roda a cada tecla e sinaliza três problemas que doctoc e markdown-toc nunca reportam:

1. Âncoras duplicadas: dois headings que geram o mesmo slug. O segundo recebe um sufixo de colisão -1, -2, então seu link NÃO é o que você adivinharia pelo texto — um #setup copiado cairá na seção errada. A verificação mostra o slug base e a âncora real com sufixo para a qual ele resolveu.

2. Níveis de heading pulados: um H2 que salta direto para um H4 sem H3 entre eles. Isso quebra o esboço do documento do qual leitores de tela e a navegação de geradores de site dependem (uma questão de WCAG 1.3.1) e torna a indentação do sumário enganosa.

3. Headings vazios: uma linha `## ` sem texto. Produzem uma âncora vazia e uma entrada em branco no sumário.

Quando tudo está limpo você recebe um visto verde. Corrija os problemas na fonte e o sumário e o relatório se atualizam juntos. Essa é exatamente a validação que um mantenedor de docs quer antes de fazer commit de um README.

Por que meu link de âncora não funciona no GitHub?

Os culpados de sempre, todos tratados corretamente por esta ferramenta:

- Underscores: o GitHub MANTÉM underscores nas âncoras, então um heading `hello_world` vira #hello_world, não #helloworld. Selecione o estilo GitHub e a ferramenta os preserva.

- Símbolos removidos entre palavras: o GitHub remove a pontuação mas NÃO colapsa os espaços que sobram. 'foo & bar' vira #foo--bar (dois hífens), porque o '&' é apagado e cada espaço vizinho vira seu próprio hífen. Um link para #foo-bar dará 404. A ferramenta reproduz esse comportamento exato do gh-slugger.

- Maiúsculas: âncoras são minúsculas. #Introduction não casa; use #introduction.

- Emojis e quase toda pontuação são removidos; o texto ao redor ainda vira slug.

- Headings duplicados recebem sufixo -1/-2 (veja a Verificação de Âncoras), então o segundo 'Setup' é #setup-1, não #setup.

Se um link ainda falhar, cole o heading aqui, escolha o estilo GitHub e copie a âncora que a ferramenta gera — ela casa com o que o GitHub renderiza.

Como se compara com doctoc ou markdown-toc?

doctoc e markdown-toc são CLIs que editam seus arquivos Markdown no lugar. Ótimos para repositórios — rode em pre-commit hook ou CI e tenha sumários sempre atualizados no controle de versão.

Esta página é o oposto: uma versão no navegador, sem instalação, da mesma funcionalidade. Trade-offs:

- Uso pontual rápido, sem instalar Node/npm, sem permissões.
- Múltiplos estilos de slug em uma UI; doctoc só emite estilo GitHub.
- O botão 'Inserir na fonte' é uma escrita única no textarea — depois você copia/salva o arquivo.
- Todo processamento local — o conteúdo do documento não é enviado.
- Para manutenção contínua do repo, doctoc ou markdown-toc continuam a resposta certa; para geração manual ocasional, isto é mais rápido.

O parser lida com blocos com cerca, headings setext e Unicode de forma comparável a essas CLIs.

Principais Recursos

• Parseia headings Markdown ATX (#) e Setext (=== / ---)
• Intervalo de níveis configurável (H1–H6 min, H2–H6 max)
• Estilos GitHub, GitLab, CommonMark + modo texto simples
• Dedup automático de slugs com sufixo -1, -2 (igual ao GitHub)
• Verificação de âncoras: sinaliza âncoras duplicadas, níveis pulados e headings vazios antes de publicar
• Ciente de Unicode: preserva diacríticos, alfabetos não-latinos, sem emoji
• Pula headings dentro de blocos com cerca (``` / ~~~) e indentados
• Remove bold / italic / inline-code / sintaxe de link nos rótulos
• Estilos de bullet: -, *, + ou numerado (1.)
• Tamanho de indent: 2, 4 ou Tab
• Insere no lugar de [TOC] ou <!-- toc -->, ou após o primeiro H1
• Preview ao vivo mostra o sumário como lista clicável
• Copia o sumário para a área de transferência
• Markdown de amostra para testar imediatamente
• 100% no cliente — seu documento não sai do navegador
• JavaScript puro — funciona offline após o primeiro carregamento