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.

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)
• 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