@docsector/docsector-reader 3.1.0 → 3.2.1

package/src/pages/guide/i18n-and-markdown.overview.en-US.md

@@ -41,9 +41,15 @@ The `_` object is the root namespace for pages. Page titles and content are **au
 
 Documentation content is written in standard Markdown with some conventions:
 
+See the dedicated manual pages for block-by-block reference:
+
+- [Paragraphs](/manual/content/blocks/paragraphs/overview/), [Headings](/manual/content/blocks/headings/overview/), [Unordered lists](/manual/content/blocks/unordered-lists/overview/), [Ordered lists](/manual/content/blocks/ordered-lists/overview/)
+- [Hints](/manual/content/blocks/hints/overview/), [Quote](/manual/content/blocks/quotes/overview/), [Code blocks](/manual/content/blocks/code-blocks/overview/), [Mermaid diagrams](/manual/content/blocks/mermaid-diagrams/overview/)
+- [Images](/manual/content/blocks/images/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expandable](/manual/content/blocks/expandable/overview/), [Tables](/manual/content/blocks/tables/overview/), [Raw HTML](/manual/content/blocks/raw-html/overview/), and [Quick Links](/manual/content/blocks/quick-links/overview/)
+
 ### Headings
 
-Use `##` through `######` for section headings. Each heading becomes a navigation anchor in the ToC tree.
+Use `##` through `######` for section headings. Each heading becomes a navigation anchor in the ToC tree using a GitHub-compatible slug, so standard README fragments such as `#table-of-contents` work in Docsector too.
 
 ### Code Blocks
 
@@ -61,6 +67,25 @@ You can render Mermaid diagrams using fenced blocks with the `mermaid` language
 ```
 ```mermaid
 flowchart TD
+  A[Start] --> B[End]
+```
+```
+
+### Math and TeX
+
+Docsector supports KaTeX-style math in standard Markdown flows, including paragraphs, alerts, and expandable content.
+
+Use single dollar delimiters for inline math such as $E = mc^2$.
+
+Use double dollar delimiters for display math:
+
+```markdown
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+Math delimiters remain literal inside inline code and fenced code blocks, so syntax examples can be documented without rendering the equation.
 
 ### GitHub Alerts
 
@@ -75,9 +100,6 @@ Docsector also supports GitHub-style alert blockquotes:
 
 Supported types are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`.
 Regular blockquotes (without `[!TYPE]`) continue to work as normal.
-  A[Start] --> B[End]
-```
-```
 
 ### Custom Attributes
 

package/src/pages/guide/i18n-and-markdown.overview.pt-BR.md

@@ -41,9 +41,15 @@ O objeto `_` é o namespace raiz para páginas. Títulos e conteúdo das página
 
 O conteúdo da documentação é escrito em Markdown padrão com algumas convenções:
 
+Veja também as páginas dedicadas do manual para cada bloco:
+
+- [Parágrafos](/manual/content/blocks/paragraphs/overview/), [Títulos](/manual/content/blocks/headings/overview/), [Listas não ordenadas](/manual/content/blocks/unordered-lists/overview/), [Listas ordenadas](/manual/content/blocks/ordered-lists/overview/)
+- [Hints](/manual/content/blocks/hints/overview/), [Citação](/manual/content/blocks/quotes/overview/), [Blocos de código](/manual/content/blocks/code-blocks/overview/), [Diagramas Mermaid](/manual/content/blocks/mermaid-diagrams/overview/)
+- [Imagens](/manual/content/blocks/images/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expansível](/manual/content/blocks/expandable/overview/), [Tabelas](/manual/content/blocks/tables/overview/), [HTML bruto](/manual/content/blocks/raw-html/overview/) e [Quick Links](/manual/content/blocks/quick-links/overview/)
+
 ### Títulos
 
-Use `##` até `######` para títulos de seção. Cada título se torna uma âncora de navegação na árvore de ToC.
+Use `##` até `######` para títulos de seção. Cada título se torna uma âncora de navegação na árvore de ToC usando slug compatível com GitHub, então fragmentos padrão de README como `#table-of-contents` também funcionam no Docsector.
 
 ### Blocos de Código
 
@@ -65,6 +71,22 @@ flowchart TD
 ```
 ```
 
+### Math e TeX
+
+O Docsector suporta fórmulas com KaTeX nos fluxos normais de Markdown, incluindo parágrafos, alertas e conteúdo expansível.
+
+Use delimitadores com um dólar para fórmulas inline, como $E = mc^2$.
+
+Use delimitadores com dois dólares para fórmulas em bloco:
+
+```markdown
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+Os delimitadores matemáticos permanecem literais dentro de código inline e fenced code, então exemplos de sintaxe podem ser documentados sem renderizar a equação.
+
 ### Alertas do GitHub
 
 O Docsector tambem suporta blockquotes de alerta no estilo do GitHub:

package/src/pages/guide/pages-and-routing.overview.en-US.md

@@ -2,6 +2,8 @@
 
 Documentation pages are defined in split registries such as `src/pages/guide.index.js` and `src/pages/manual.index.js`. Each entry maps a URL path to its configuration, translatable data, and optional metadata.
 
+In the current manual, it is common to keep core UI references under `/basic`, end-user content blocks under `/content/blocks`, structural concepts under `/content/structures`, and legacy engine-facing aliases under `/components`.
+
 ## Page Entry Structure
 
 ```javascript
@@ -35,11 +37,11 @@ Documentation pages are defined in split registries such as `src/pages/guide.ind
 Set `config: null` to create a non-navigable grouping node. This is useful for creating section titles in the sidebar menu:
 
 ```javascript
-'/components': {
+'/content/blocks': {
   config: null,
   data: {
-    'en-US': { title: 'Components' },
-    'pt-BR': { title: 'Componentes' }
+    'en-US': { title: 'Blocks' },
+    'pt-BR': { title: 'Blocos' }
   }
 }
 ```
@@ -51,8 +53,8 @@ Pages are grouped in the sidebar by their **basepath** (second URL segment). The
 ```javascript
 menu: {
   header: {
-    icon: 'widgets',
-    label: 'Components'
+    icon: 'notes',
+    label: 'Content'
   }
 }
 ```
@@ -72,11 +74,11 @@ Each page requires Markdown files following this naming pattern:
 
 `src/pages/{book}/{path}.{subpage}.{lang}.md`
 
-For example, a page at `/components/d-page` with book `manual`:
+For example, a page at `/content/blocks/headings` with book `manual`:
 
-- `src/pages/manual/components/d-page.overview.en-US.md`
-- `src/pages/manual/components/d-page.overview.pt-BR.md`
-- `src/pages/manual/components/d-page.showcase.en-US.md` (if showcase enabled)
+- `src/pages/manual/content/blocks/headings.overview.en-US.md`
+- `src/pages/manual/content/blocks/headings.overview.pt-BR.md`
+- `src/pages/manual/content/blocks/headings.showcase.en-US.md` (if showcase enabled)
 
 ## Route Generation
 

package/src/pages/guide/pages-and-routing.overview.pt-BR.md

@@ -2,6 +2,8 @@
 
 As páginas de documentação são definidas em registros separados, como `src/pages/guide.index.js` e `src/pages/manual.index.js`. Cada entrada mapeia um caminho URL para sua configuração, dados traduzíveis e metadata opcional.
 
+No manual atual, é comum manter referências centrais de UI sob `/basic`, blocos de conteúdo voltados ao usuário final sob `/content/blocks`, conceitos estruturais sob `/content/structures` e aliases legados voltados à engine sob `/components`.
+
 ## Estrutura de uma Entrada
 
 ```javascript
@@ -35,11 +37,11 @@ As páginas de documentação são definidas em registros separados, como `src/p
 Defina `config: null` para criar um nó de agrupamento não-navegável. Útil para criar títulos de seção no menu lateral:
 
 ```javascript
-'/components': {
+'/content/blocks': {
   config: null,
   data: {
-    'en-US': { title: 'Components' },
-    'pt-BR': { title: 'Componentes' }
+    'en-US': { title: 'Blocks' },
+    'pt-BR': { title: 'Blocos' }
   }
 }
 ```
@@ -51,8 +53,8 @@ Páginas são agrupadas no menu lateral pelo seu **basepath** (segundo segmento
 ```javascript
 menu: {
   header: {
-    icon: 'widgets',
-    label: 'Components'
+    icon: 'notes',
+    label: 'Conteúdo'
   }
 }
 ```
@@ -72,11 +74,11 @@ Cada página requer arquivos Markdown seguindo este padrão de nomenclatura:
 
 `src/pages/{book}/{path}.{subpage}.{lang}.md`
 
-Por exemplo, uma página em `/components/d-page` com book `manual`:
+Por exemplo, uma página em `/content/blocks/headings` com book `manual`:
 
-- `src/pages/manual/components/d-page.overview.en-US.md`
-- `src/pages/manual/components/d-page.overview.pt-BR.md`
-- `src/pages/manual/components/d-page.showcase.en-US.md` (se showcase habilitado)
+- `src/pages/manual/content/blocks/headings.overview.en-US.md`
+- `src/pages/manual/content/blocks/headings.overview.pt-BR.md`
+- `src/pages/manual/content/blocks/headings.showcase.en-US.md` (se showcase habilitado)
 
 ## Geração de Rotas
 

package/src/pages/guide.index.js

@@ -120,34 +120,6 @@ export default {
     }
   },
 
-  '/alerts-and-blockquotes': {
-    config: {
-      icon: 'notification_important',
-      status: 'done',
-      meta: {
-        description: {
-          'en-US': 'Alerts & Blockquotes — Documentation of Docsector Reader',
-          'pt-BR': 'Alertas & Blockquotes — Documentacao do Docsector Reader'
-        }
-      },
-      book: 'guide',
-      menu: {},
-      subpages: {
-        showcase: false
-      }
-    },
-    data: {
-      'en-US': { title: 'Alerts & Blockquotes' },
-      'pt-BR': { title: 'Alertas & Blockquotes' }
-    },
-    metadata: {
-      tags: {
-        'en-US': 'alerts blockquotes github note tip important warning caution markdown quote admonition',
-        'pt-BR': 'alertas blockquotes github note tip important warning caution markdown citação admonition'
-      }
-    }
-  },
-
   '/theming': {
     config: {
       icon: 'palette',

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

@@ -0,0 +1,27 @@
+## Overview
+
+Branding controls the visual identity and quick-access links shown at the top of the documentation menu.
+
+It covers the project logo, name, current version label, and the external links that appear below the branding block.
+
+## Main Configuration
+
+Branding data comes from `docsector.config.js`:
+
+- `branding.logo`
+- `branding.name`
+- `branding.version`
+- `links.github`, `links.discussions`, `links.chat`, `links.email`
+- `links.changelog`, `links.roadmap`, `links.sponsor`, `links.explore`
+
+## What Readers Notice
+
+- A recognizable project identity in the menu
+- Faster access to repository and community links
+- A stable place to understand which docs set they are reading
+
+## Notes
+
+- Set a link to `null` to hide it from the menu.
+- A square or near-square logo usually fits best in the sidebar.
+- Keep the visible project name short enough to scan quickly.

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

@@ -0,0 +1,27 @@
+## Visão Geral
+
+Branding controla a identidade visual e os links de acesso rápido exibidos no topo do menu da documentação.
+
+Ele cobre o logo do projeto, o nome, o label da versão atual e os links externos que aparecem abaixo do bloco de branding.
+
+## Configuração Principal
+
+Os dados de branding vêm de `docsector.config.js`:
+
+- `branding.logo`
+- `branding.name`
+- `branding.version`
+- `links.github`, `links.discussions`, `links.chat`, `links.email`
+- `links.changelog`, `links.roadmap`, `links.sponsor`, `links.explore`
+
+## O Que o Leitor Percebe
+
+- Uma identidade reconhecível do projeto no menu
+- Acesso mais rápido ao repositório e aos links da comunidade
+- Um lugar estável para entender qual conjunto de docs está sendo lido
+
+## Observações
+
+- Defina um link como `null` para escondê-lo do menu.
+- Um logo quadrado ou quase quadrado costuma funcionar melhor na barra lateral.
+- Mantenha o nome visível do projeto curto o suficiente para leitura rápida.

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.