@docsector/docsector-reader 3.2.0 → 3.2.2

package/src/pages/manual/{components → basic}/d-menu.overview.en-US.md

@@ -1,6 +1,14 @@
 ## Overview
 
-`DMenu` is the **left sidebar navigation** component. It renders the project branding, external links, search functionality, and the documentation page tree.
+Navigation Menu is the **left sidebar** used to explore the documentation.
+
+Under the hood, this page describes the `DMenu` implementation.
+
+## Focused Pages in Basic
+
+- [Search](/manual/basic/search/overview/)
+- [Branding](/manual/basic/branding/overview/)
+- [Version Switcher](/manual/basic/version-switcher/overview/)
 
 ## Features
 
@@ -21,7 +29,7 @@ Search is debounced by 300ms and supports the current locale with en-US fallback
 
 ## Branding Section
 
-Reads from `docsector.config.js`:
+The menu reads its branding data from `docsector.config.js`:
 
 - `branding.logo` — Project logo image
 - `branding.name` — Project name text
@@ -60,4 +68,4 @@ Items without a header are displayed as standalone entries.
 
 ## Auto-Scroll
 
-On mount and after navigation, DMenu automatically scrolls to the currently active menu item, centering it in the viewport with a smooth 300ms animation.
+On mount and after navigation, the menu automatically scrolls to the currently active item, centering it in the viewport with a smooth 300ms animation.

package/src/pages/manual/{components → basic}/d-menu.overview.pt-BR.md

@@ -1,6 +1,14 @@
 ## Visão Geral
 
-`DMenu` é o componente de **navegação lateral esquerda**. Ele renderiza o branding do projeto, links externos, funcionalidade de busca e a árvore de páginas de documentação.
+Menu de Navegação é a **barra lateral esquerda** usada para explorar a documentação.
+
+Na implementação, esta página descreve o `DMenu`.
+
+## Páginas Focadas no Basic
+
+- [Busca](/manual/basic/search/overview/)
+- [Branding](/manual/basic/branding/overview/)
+- [Seletor de Versão](/manual/basic/version-switcher/overview/)
 
 ## Funcionalidades
 
@@ -21,7 +29,7 @@ A busca tem debounce de 300ms e suporta o locale atual com fallback para en-US.
 
 ## Seção de Branding
 
-Lê do `docsector.config.js`:
+O menu lê seus dados de branding a partir de `docsector.config.js`:
 
 - `branding.logo` — Imagem do logo do projeto
 - `branding.name` — Texto do nome do projeto
@@ -60,4 +68,4 @@ Itens sem header são exibidos como entradas independentes.
 
 ## Auto-Scroll
 
-No mount e após navegação, DMenu automaticamente faz scroll até o item de menu ativo, centralizando-o no viewport com uma animação suave de 300ms.
+No mount e após navegação, o menu automaticamente faz scroll até o item ativo, centralizando-o no viewport com uma animação suave de 300ms.

package/src/pages/manual/{components → basic}/d-page-anchor.overview.en-US.md

@@ -1,6 +1,8 @@
 ## Overview
 
-`DPageAnchor` renders the **Table of Contents (ToC) tree** in the right-side drawer. It displays a navigable tree of all headings on the current page, allowing users to jump directly to any section.
+Table of Contents is the **right-side navigation tree** that lists the headings of the current page.
+
+Under the hood, this behavior is powered by `DPageAnchor`.
 
 ## How It Works
 
@@ -11,7 +13,7 @@
 
 ## Store Integration
 
-DPageAnchor interacts with these store state/getters:
+The implementation interacts with these store state/getters:
 
 - `page/nodes` — The tree structure of headings
 - `page/nodesExpanded` — Which tree nodes are expanded
@@ -37,7 +39,7 @@ The root node (from DH1) shows the page title from i18n when no label is set:
 
 ## Scroll Synchronization
 
-When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which iterates over registered anchors and selects the one closest to the current scroll position. This keeps the ToC tree in sync with the visible content.
+When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which iterates over registered anchors and selects the one closest to the current scroll position. This keeps the table of contents in sync with the visible content.
 
 ## Lifecycle
 

package/src/pages/manual/{components → basic}/d-page-anchor.overview.pt-BR.md

@@ -1,6 +1,8 @@
 ## Visão Geral
 
-`DPageAnchor` renderiza a **árvore de Índice (ToC)** no drawer lateral direito. Exibe uma árvore navegável de todos os títulos na página atual, permitindo que os usuários saltem diretamente para qualquer seção.
+Índice da Página é a **árvore de navegação lateral direita** que lista os títulos da página atual.
+
+Na implementação, esse comportamento é sustentado por `DPageAnchor`.
 
 ## Como Funciona
 
@@ -11,7 +13,7 @@
 
 ## Integração com Store
 
-DPageAnchor interage com estes estados/getters da store:
+A implementação interage com estes estados/getters da store:
 
 - `page/nodes` — A estrutura em árvore dos títulos
 - `page/nodesExpanded` — Quais nós da árvore estão expandidos
@@ -37,7 +39,7 @@ O nó raiz (do DH1) mostra o título da página do i18n quando nenhum label é d
 
 ## Sincronização de Scroll
 
-Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que itera sobre as âncoras registradas e seleciona a mais próxima da posição de scroll atual. Isso mantém a árvore de ToC sincronizada com o conteúdo visível.
+Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que itera sobre as âncoras registradas e seleciona a mais próxima da posição de scroll atual. Isso mantém o índice sincronizado com o conteúdo visível.
 
 ## Ciclo de Vida
 

package/src/pages/manual/{components → basic}/d-page-meta.overview.en-US.md

@@ -1,6 +1,14 @@
 ## Overview
 
-`DPageMeta` is the **page footer** component that displays GitHub integration, translation progress, and prev/next navigation links.
+Page Footer is the **bottom information area** that shows GitHub actions, translation progress, and previous/next navigation.
+
+Under the hood, this page describes `DPageMeta`.
+
+## Focused Pages in Basic
+
+- [Edit on GitHub](/manual/basic/edit-on-github/overview/)
+- [Translation Progress](/manual/basic/translation-progress/overview/)
+- [Previous & Next](/manual/basic/previous-and-next/overview/)
 
 ## Sections
 
@@ -49,4 +57,4 @@ github: {
 
 ## Disabling
 
-DPageMeta is automatically excluded when `DPage` has `disableNav` prop set to `true`.
+The footer is automatically excluded when `DPage` has `disableNav` prop set to `true`.

package/src/pages/manual/{components → basic}/d-page-meta.overview.pt-BR.md

@@ -1,6 +1,14 @@
 ## Visão Geral
 
-`DPageMeta` é o componente de **rodapé de página** que exibe integração com GitHub, progresso de tradução e links de navegação anterior/próximo.
+Rodapé da Página é a **área inferior de informação** que exibe ações de GitHub, progresso de tradução e links de navegação anterior/próximo.
+
+Na implementação, esta página descreve o `DPageMeta`.
+
+## Páginas Focadas no Basic
+
+- [Editar no GitHub](/manual/basic/edit-on-github/overview/)
+- [Progresso de Tradução](/manual/basic/translation-progress/overview/)
+- [Anterior e Próximo](/manual/basic/previous-and-next/overview/)
 
 ## Seções
 
@@ -49,4 +57,4 @@ github: {
 
 ## Desabilitando
 
-DPageMeta é automaticamente excluído quando `DPage` tem a prop `disableNav` definida como `true`.
+O rodapé é automaticamente excluído quando `DPage` tem a prop `disableNav` definida como `true`.

package/src/pages/manual/basic/edit-on-github.overview.en-US.md

@@ -0,0 +1,26 @@
+## Overview
+
+Edit on GitHub gives readers a direct path from the current page to its Markdown source file.
+
+This makes small documentation improvements faster, especially when the reader is already on the page that needs a change.
+
+## What It Uses
+
+The link is built from:
+
+- `github.editBaseUrl` in `docsector.config.js`
+- The current page path
+- The current locale
+
+## Status-Aware Labels
+
+The button label adapts to page status:
+
+- `done` or `new` → edit the page
+- `draft` → complete the page
+- `empty` → start the page
+
+## Notes
+
+- The target file follows the book, path, subpage, and locale naming convention.
+- This action appears in the page footer area.

package/src/pages/manual/basic/edit-on-github.overview.pt-BR.md

@@ -0,0 +1,26 @@
+## Visão Geral
+
+Editar no GitHub dá ao leitor um caminho direto da página atual até o arquivo Markdown de origem.
+
+Isso acelera pequenas melhorias na documentação, especialmente quando o leitor já está na página que precisa de ajuste.
+
+## O Que Ele Usa
+
+O link é montado a partir de:
+
+- `github.editBaseUrl` em `docsector.config.js`
+- O caminho da página atual
+- O locale atual
+
+## Labels Sensíveis ao Status
+
+O label do botão se adapta ao status da página:
+
+- `done` ou `new` → editar a página
+- `draft` → completar a página
+- `empty` → começar a página
+
+## Observações
+
+- O arquivo de destino segue a convenção de nomes baseada em book, path, subpage e locale.
+- Essa ação aparece na área de rodapé da página.

package/src/pages/manual/basic/previous-and-next.overview.en-US.md

@@ -0,0 +1,17 @@
+## Overview
+
+Previous & Next adds directional links to the pages that come immediately before and after the current one.
+
+It helps readers continue through a documentation sequence without returning to the sidebar each time.
+
+## How It Decides
+
+- It uses the current page position in the route sequence.
+- Only visible documentation pages are considered.
+- Links are shown only when an adjacent page exists.
+
+## Reader Benefit
+
+- Faster linear reading
+- Easier progression through tutorials and references
+- Clearer sense of where the current page sits in the manual

package/src/pages/manual/basic/previous-and-next.overview.pt-BR.md

@@ -0,0 +1,17 @@
+## Visão Geral
+
+Anterior e Próximo adiciona links direcionais para as páginas imediatamente anterior e posterior à página atual.
+
+Isso ajuda o leitor a continuar por uma sequência de documentação sem voltar à barra lateral toda vez.
+
+## Como Ele Decide
+
+- Usa a posição da página atual na sequência de rotas.
+- Considera apenas páginas de documentação visíveis.
+- Os links só aparecem quando existe uma página adjacente.
+
+## Benefício para o Leitor
+
+- Leitura linear mais rápida
+- Progressão mais simples por tutoriais e referências
+- Noção mais clara de onde a página atual está no manual

package/src/pages/manual/basic/search.overview.en-US.md

@@ -0,0 +1,24 @@
+## Overview
+
+Search helps readers find documentation pages quickly from the left sidebar.
+
+Under the hood, this experience is powered by the menu search flow used by `DMenu`.
+
+## What Search Looks At
+
+- Page titles and localized labels
+- `metadata.tags` defined in `src/pages/*.index.js`
+- Markdown content from overview, showcase, and vs pages
+
+## Behavior
+
+- Search starts when the query has more than one character.
+- Results follow the active documentation version and current book.
+- The current locale is preferred, with `en-US` as fallback when needed.
+- Input is debounced so fast typing does not rebuild results on every keystroke.
+
+## Good Practices
+
+- Keep page titles descriptive.
+- Add useful search tags close to the page entry in the registry.
+- Prefer short, concrete wording so readers can guess the right term easily.

package/src/pages/manual/basic/search.overview.pt-BR.md

@@ -0,0 +1,24 @@
+## Visão Geral
+
+Busca ajuda o leitor a encontrar páginas da documentação rapidamente pela barra lateral esquerda.
+
+Na implementação, essa experiência é sustentada pelo fluxo de busca usado em `DMenu`.
+
+## O Que a Busca Considera
+
+- Títulos de página e labels localizados
+- `metadata.tags` definidos em `src/pages/*.index.js`
+- Conteúdo Markdown das páginas overview, showcase e vs
+
+## Comportamento
+
+- A busca começa quando a consulta tem mais de um caractere.
+- Os resultados seguem a versão ativa da documentação e o book atual.
+- O locale atual tem prioridade, com fallback para `en-US` quando necessário.
+- O input usa debounce para que a digitação rápida não reconstrua os resultados a cada tecla.
+
+## Boas Práticas
+
+- Mantenha títulos de página descritivos.
+- Adicione tags de busca úteis perto da entrada da página no registry.
+- Prefira termos curtos e concretos para o leitor adivinhar a palavra certa com facilidade.

package/src/pages/manual/basic/translation-progress.overview.en-US.md

@@ -0,0 +1,19 @@
+## Overview
+
+Translation Progress shows how complete the current locale is and how many translations are available for the page.
+
+It helps readers and maintainers understand whether a page is fully localized or still in progress.
+
+## Visible Signals
+
+- A progress chip for the active locale
+- A chip showing how many locales are available compared to the configured total
+
+## Data Source
+
+The progress view relies on translation metadata such as `_sections.done` and `_sections.count`.
+
+## Notes
+
+- This information appears in the page footer area.
+- Translation progress is more useful when section metadata is kept accurate.

package/src/pages/manual/basic/translation-progress.overview.pt-BR.md

@@ -0,0 +1,19 @@
+## Visão Geral
+
+Progresso de Tradução mostra o quanto o locale atual está completo e quantas traduções estão disponíveis para a página.
+
+Isso ajuda leitores e mantenedores a entender se uma página está totalmente localizada ou ainda em andamento.
+
+## Sinais Visíveis
+
+- Um chip de progresso para o locale ativo
+- Um chip mostrando quantos locales estão disponíveis em relação ao total configurado
+
+## Fonte dos Dados
+
+A visualização de progresso depende de metadados de tradução como `_sections.done` e `_sections.count`.
+
+## Observações
+
+- Essa informação aparece na área de rodapé da página.
+- O progresso de tradução fica mais útil quando os metadados de seções são mantidos corretos.

package/src/pages/manual/basic/version-switcher.overview.en-US.md

@@ -0,0 +1,28 @@
+## Overview
+
+Version Switcher lets readers move between the current documentation and archived or alternative versions.
+
+It helps keep long-lived docs usable when the project supports more than one release line.
+
+## How It Works
+
+- The selector reads the configured versions list.
+- Current docs usually stay on unprefixed routes.
+- Archived versions can use a route prefix such as `/v0.x`.
+- When possible, the switcher tries to open the equivalent page in the target version.
+- If the same page does not exist there, it falls back to the first matching route in that book.
+
+## Release Badges
+
+The selector can show badges such as:
+
+- `released`
+- `draft`
+- `deprecated`
+
+Custom badge labels and colors can also be configured per version.
+
+## Notes
+
+- A version entry may also point to an external URL.
+- Keep labels short so the dropdown stays easy to scan.

package/src/pages/manual/basic/version-switcher.overview.pt-BR.md

@@ -0,0 +1,28 @@
+## Visão Geral
+
+Seletor de Versão permite que o leitor navegue entre a documentação atual e versões arquivadas ou alternativas.
+
+Ele ajuda a manter docs de longa duração utilizáveis quando o projeto suporta mais de uma linha de release.
+
+## Como Funciona
+
+- O seletor lê a lista de versões configuradas.
+- A documentação atual normalmente fica em rotas sem prefixo.
+- Versões arquivadas podem usar um prefixo como `/v0.x`.
+- Quando possível, o seletor tenta abrir a página equivalente na versão de destino.
+- Se a mesma página não existir lá, ele faz fallback para a primeira rota compatível naquele book.
+
+## Badges de Release
+
+O seletor pode mostrar badges como:
+
+- `released`
+- `draft`
+- `deprecated`
+
+Também é possível configurar labels e cores customizadas por versão.
+
+## Observações
+
+- Uma entrada de versão também pode apontar para uma URL externa.
+- Mantenha os labels curtos para o dropdown continuar fácil de escanear.

package/src/pages/manual/components/d-subpage.overview.en-US.md

@@ -4,7 +4,7 @@
 
 ## How It Works
 
-DSubpage generates a deterministic numeric ID from the current route path using a hash function. This ID is passed to `DPageSection` to ensure unique component keys across page navigations.
+DSubpage generates a deterministic numeric ID from the current route path using a hash function. This ID is passed to `DPageSection` to keep per-page renderer indexes stable across page navigations.
 
 ## Template
 
@@ -34,7 +34,7 @@ const id = computed(() => {
 })
 ```
 
-This ensures that each page generates a unique set of anchor IDs, preventing collisions when switching between pages.
+This keeps per-page renderer state isolated when switching between pages. Markdown section headings themselves use GitHub-compatible slugs derived from the heading text, so README-style Table of Contents links keep working.
 
 ## When to Use
 

package/src/pages/manual/components/d-subpage.overview.pt-BR.md

@@ -4,7 +4,7 @@
 
 ## Como Funciona
 
-DSubpage gera um ID numérico determinístico a partir do caminho da rota atual usando uma função hash. Esse ID é passado ao `DPageSection` para garantir chaves de componente únicas entre navegações de página.
+DSubpage gera um ID numérico determinístico a partir do caminho da rota atual usando uma função hash. Esse ID é passado ao `DPageSection` para manter estáveis os índices internos do renderer em cada página.
 
 ## Template
 
@@ -34,7 +34,7 @@ const id = computed(() => {
 })
 ```
 
-Isso garante que cada página gere um conjunto único de IDs de âncora, prevenindo colisões ao navegar entre páginas.
+Isso mantém o estado interno do renderer isolado ao navegar entre páginas. Os headings Markdown em si usam slugs compatíveis com GitHub derivados do texto do título, então links de Table of Contents no estilo README continuam funcionando.
 
 ## Quando Usar
 

package/src/pages/manual/content/blocks/code-blocks.overview.en-US.md

@@ -0,0 +1,55 @@
+## Overview
+
+Code blocks are authored with standard fenced Markdown and rendered with syntax highlighting, line numbers, copy-to-clipboard, and optional metadata such as filenames, tabs, and breadcrumbs.
+
+Docsector uses Prism.js for highlighting and automatically adapts the visual style to light and dark themes.
+
+## Basic Syntax
+
+````markdown
+```bash
+npm install
+npm run dev
+```
+````
+
+## Supported Languages
+
+The built-in documentation currently ships with support for:
+
+- `php`
+- `bash`
+- `html`
+- `javascript`
+
+Additional Prism languages can be added when the project needs them.
+
+## Useful Attributes
+
+Code fences support extra metadata with `:attr;` syntax:
+
+| Attribute | Purpose |
+|-----------|---------|
+| `filename` | Shows a filename in the metadata bar |
+| `group` | Joins consecutive blocks into tabs |
+| `tab` | Sets the visible tab label |
+| `breadcrumb` | Shows a path-like breadcrumb above the active block |
+
+## What Readers Get
+
+- Language-aware syntax highlighting
+- Line numbers on multi-line snippets
+- Copy button in the metadata bar
+- Tabs for grouped examples
+- Breadcrumbs and file icons when metadata is provided
+
+## Example With Tabs
+
+````markdown
+```php :group="example"; :tab="example.php"; :breadcrumb="src > example.php";
+echo "Hello";
+```
+```bash :group="example"; :tab="example.sh"; :breadcrumb="scripts > example.sh";
+echo "Hello"
+```
+````

package/src/pages/manual/content/blocks/code-blocks.overview.pt-BR.md

@@ -0,0 +1,55 @@
+## Visão Geral
+
+Blocos de código são escritos com cercas Markdown padrão e renderizados com syntax highlighting, números de linha, botão de cópia e metadados opcionais como nome de arquivo, abas e breadcrumbs.
+
+O Docsector usa Prism.js para o highlighting e adapta automaticamente o visual aos modos claro e escuro.
+
+## Sintaxe Básica
+
+````markdown
+```bash
+npm install
+npm run dev
+```
+````
+
+## Linguagens Suportadas
+
+A documentação padrão do projeto já vem com suporte para:
+
+- `php`
+- `bash`
+- `html`
+- `javascript`
+
+Outras linguagens podem ser adicionadas quando o projeto precisar.
+
+## Atributos Úteis
+
+As fences de código aceitam metadados extras com a sintaxe `:attr;`:
+
+| Atributo | Finalidade |
+|----------|------------|
+| `filename` | Mostra um nome de arquivo na barra de metadados |
+| `group` | Junta blocos consecutivos em abas |
+| `tab` | Define o rótulo visível da aba |
+| `breadcrumb` | Mostra um caminho acima do bloco ativo |
+
+## O Que o Leitor Recebe
+
+- Syntax highlighting por linguagem
+- Números de linha em snippets com várias linhas
+- Botão de cópia na barra de metadados
+- Abas para exemplos agrupados
+- Breadcrumbs e ícones de arquivo quando há metadados
+
+## Exemplo com Abas
+
+````markdown
+```php :group="example"; :tab="example.php"; :breadcrumb="src > example.php";
+echo "Hello";
+```
+```bash :group="example"; :tab="example.sh"; :breadcrumb="scripts > example.sh";
+echo "Hello"
+```
+````

package/src/pages/manual/{components/d-page-source-code.showcase.en-US.md → content/blocks/code-blocks.showcase.en-US.md}

@@ -1,6 +1,6 @@
 ## Showcase
 
-Here are code blocks in different languages demonstrating the DPageSourceCode component:
+Here are code blocks in different languages showing how Docsector renders technical examples:
 
 ### PHP Example
 
@@ -90,17 +90,19 @@ return [
   '/deployment' => 'DeploymentPage',
   '/plugins' => 'PluginsPage',
   '/theming' => 'ThemingPage',
-  '/components' => 'ComponentsPage',
-  '/components/d-page' => 'DPageOverview',
-  '/components/d-page-section' => 'DPageSectionOverview',
-  '/components/d-page-source-code' => 'DPageSourceCodeOverview',
-  '/components/d-menu' => 'DMenuOverview',
-  '/components/d-headings' => 'DHeadingsOverview',
-  '/components/d-mermaid-diagram' => 'DMermaidDiagramOverview',
-  '/components/d-page-blockquote' => 'DPageBlockquoteOverview',
-  '/components/d-quick-links' => 'DQuickLinksOverview',
-  '/manual' => 'ManualIndex',
-  '/manual/showcase' => 'ManualShowcase',
+  '/basic' => 'BasicPage',
+  '/basic/d-menu' => 'NavigationMenuOverview',
+  '/basic/d-page-anchor' => 'TableOfContentsOverview',
+  '/basic/d-page-meta' => 'PageFooterOverview',
+  '/content/structures/page' => 'PageOverview',
+  '/content/blocks' => 'BlocksSection',
+  '/content/blocks/paragraphs' => 'ParagraphsOverview',
+  '/content/blocks/headings' => 'HeadingsOverview',
+  '/content/blocks/code-blocks' => 'CodeBlocksOverview',
+  '/content/blocks/mermaid-diagrams' => 'MermaidDiagramsOverview',
+  '/content/blocks/quotes' => 'QuoteOverview',
+  '/content/blocks/expandable' => 'ExpandableOverview',
+  '/content/blocks/quick-links' => 'QuickLinksOverview',
   '/guide' => 'GuideIndex',
   '/guide/markdown' => 'MarkdownGuide',
   '/guide/i18n' => 'I18nGuide',