← Guias

Guia Sanctuary

Feature: Navegação e Leitura Estrutural

O Sanctuary Reader gera índice automático, barra de progresso e estatísticas para navegar melhor em documentos Markdown longos.

Atualizado
navegacaoeleituradiscoverysanctuary
Neste guia
  1. O que é
  2. Objetivo no produto
  3. Como o usuário usa
  4. Valor entregue
  5. Elementos de interface envolvidos
  6. Evidências no código
  7. O que essa feature revela sobre o produto
  8. Limitações e comportamento implícito
  9. Papel da feature no produto

O que é

Esta feature 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.

Objetivo no produto

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 o usuário usa

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

Valor entregue

  • 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 essa feature 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 da feature no produto

Esta feature sustenta a promessa de “leitor inteligente”. Ela 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.