Índice automático e progresso de leitura em Markdown

Como funciona o índice automático

O índice automático organiza o documento para leitura longa. Em vez de tratar o Markdown como uma página contínua, o Sanctuary o transforma em seções navegáveis, com índice, progresso e métricas.

Para que serve

O objetivo é reduzir desorientação em documentos extensos. O usuário precisa saber onde está, quanto falta e como saltar rapidamente entre partes relevantes.

Como usar

O documento é carregado e o índice lateral é montado a partir dos headings.
O usuário navega pelas seções usando a lista lateral.
Ao rolar o conteúdo, o item ativo do índice é atualizado automaticamente.
A sidebar mostra palavras, tempo estimado e número de seções.
A barra de progresso superior indica quanto do documento já foi percorrido.

Benefícios

melhora a orientação em documentos longos;
reforça a sensação de progresso;
ajuda a localizar trechos por estrutura, não só por scroll;
prepara o terreno para modos avançados como foco, cards, estudo guiado e slides.

Elementos de interface envolvidos

sidebar com estatísticas;
lista de headings clicável;
barra de progresso superior;
agrupamento interno em blocos de seção.

Evidências no código

src/components/reader/ReaderSidebar.astro define a sidebar, as métricas e a lista estrutural de seções.
src/scripts/reader/reader-toc.js gera o índice clicável, sincroniza o item ativo com o scroll e atualiza as métricas laterais.
src/components/reader/ReaderProgressBar.astro e src/scripts/reader/reader-core.js controlam a barra de progresso superior.
src/scripts/reader/reader-core.js encapsula o conteúdo em blocos de seção para dar suporte a foco, estudo guiado, cards e navegação estrutural.

O que esse recurso revela sobre o produto

O Sanctuary foi desenhado para leitura longa e orientada, não para consumo casual de um snippet curto. O uso de TOC ativo, progresso e agrupamento por seção indica preocupação com materiais extensos e hierárquicos.

Limitações e comportamento implícito

o TOC depende exclusivamente de headings Markdown usados como seção pelo Reader, hoje H2 e H3;
a métrica de seções considera apenas headings que viram blocos de seção, isto é, H2 e H3;
documentos mal estruturados perdem qualidade de navegação;
durante leitura guiada, a navegação pelo TOC é bloqueada para evitar conflitos de modo.

Papel do recurso no produto

Esse recurso sustenta a promessa de “leitor inteligente”. Ele dá forma ao documento e o torna administrável para estudo, revisão e apresentação, preparando a base para os modos mais opinativos do produto.