@docsector/docsector-reader 3.1.0 → 3.2.1

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',

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

@@ -1,6 +1,6 @@
 ## Demonstração
 
-Aqui estão blocos de código em diferentes linguagens demonstrando o componente DPageSourceCode:
+Aqui estão blocos de código em diferentes linguagens mostrando como o Docsector renderiza exemplos técnicos:
 
 ### Exemplo PHP
 
@@ -84,32 +84,34 @@ console.log('Exemplo de breadcrumb gigante')
 
 ```php :group="exemplo-longo"; :tab="rotas.php"; :breadcrumb="src > rotas > rotas.php";
 return [
-  '/visao-geral' => 'PaginaVisaoGeral',
-  '/primeiros-passos' => 'PaginaPrimeirosPassos',
-  '/configuracao' => 'PaginaConfiguracao',
-  '/deploy' => 'PaginaDeploy',
+  '/overview' => 'PaginaVisaoGeral',
+  '/getting-started' => 'PaginaPrimeirosPassos',
+  '/configuration' => 'PaginaConfiguracao',
+  '/deployment' => 'PaginaDeploy',
   '/plugins' => 'PaginaPlugins',
-  '/temas' => 'PaginaTemas',
-  '/componentes' => 'PaginaComponentes',
-  '/componentes/d-page' => 'DPageVisaoGeral',
-  '/componentes/d-page-section' => 'DPageSectionVisaoGeral',
-  '/componentes/d-page-source-code' => 'DPageSourceCodeVisaoGeral',
-  '/componentes/d-menu' => 'DMenuVisaoGeral',
-  '/componentes/d-headings' => 'DHeadingsVisaoGeral',
-  '/componentes/d-mermaid-diagram' => 'DMermaidDiagramVisaoGeral',
-  '/componentes/d-page-blockquote' => 'DPageBlockquoteVisaoGeral',
-  '/componentes/d-quick-links' => 'DQuickLinksVisaoGeral',
-  '/manual' => 'IndiceManual',
-  '/manual/demonstracao' => 'DemonstracaoManual',
-  '/guia' => 'IndiceGuia',
-  '/guia/markdown' => 'GuiaMarkdown',
-  '/guia/i18n' => 'GuiaI18n',
-  '/guia/rotas' => 'GuiaRotas',
-  '/guia/busca' => 'GuiaBusca',
-  '/guia/api' => 'GuiaApi',
-  '/guia/mcp' => 'GuiaMcp',
-  '/guia/releases' => 'GuiaReleases',
-  '/guia/changelog' => 'GuiaChangelog',
+  '/theming' => 'PaginaTemas',
+  '/basic' => 'PaginaBasico',
+  '/basic/d-menu' => 'MenuDeNavegacaoVisaoGeral',
+  '/basic/d-page-anchor' => 'IndiceDaPaginaVisaoGeral',
+  '/basic/d-page-meta' => 'RodapeDaPaginaVisaoGeral',
+  '/content/structures/page' => 'PaginaVisaoGeral',
+  '/content/blocks' => 'SecaoBlocos',
+  '/content/blocks/paragraphs' => 'ParagrafosVisaoGeral',
+  '/content/blocks/headings' => 'TitulosVisaoGeral',
+  '/content/blocks/code-blocks' => 'BlocosDeCodigoVisaoGeral',
+  '/content/blocks/mermaid-diagrams' => 'DiagramasMermaidVisaoGeral',
+  '/content/blocks/quotes' => 'CitacaoVisaoGeral',
+  '/content/blocks/expandable' => 'ExpansivelVisaoGeral',
+  '/content/blocks/quick-links' => 'QuickLinksVisaoGeral',
+  '/guide' => 'IndiceGuia',
+  '/guide/markdown' => 'GuiaMarkdown',
+  '/guide/i18n' => 'GuiaI18n',
+  '/guide/routing' => 'GuiaRotas',
+  '/guide/search' => 'GuiaBusca',
+  '/guide/api' => 'GuiaApi',
+  '/guide/mcp' => 'GuiaMcp',
+  '/guide/releases' => 'GuiaReleases',
+  '/guide/changelog' => 'GuiaChangelog',
 ];
 ```
 ```bash :group="exemplo-longo"; :tab="deploy.sh"; :breadcrumb="scripts > deploy.sh";

package/src/pages/manual/{components/d-page-expandable.overview.en-US.md → content/blocks/expandable.overview.en-US.md}

@@ -1,19 +1,10 @@
 ## Overview
 
-`DPageExpandable` renders a collapsible content section backed by the Markdown custom element `<d-expandable>`.
+Expandable blocks collapse secondary content behind a clickable title.
 
-It is designed for secondary content that should stay available without stretching the main reading flow. The body keeps the same rich Markdown features already available in page sections, including lists, blockquotes, code blocks, Mermaid diagrams, tables, raw HTML, and quick links.
+They are a good fit when the main section should stay short, but readers may still need optional details, checklists, appendix material, or longer examples.
 
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `String` | `''` | Header label shown in the expandable trigger |
-| `open` | `Boolean` | `false` | Initial expanded state |
-
-## Slot
-
-The default slot receives the parsed content body.
+The block is authored with the custom Markdown element `<d-expandable>`.
 
 ## HTML Example
 

package/src/pages/manual/{components/d-page-expandable.overview.pt-BR.md → content/blocks/expandable.overview.pt-BR.md}

@@ -1,19 +1,10 @@
 ## Visão Geral
 
-`DPageExpandable` renderiza uma seção recolhível baseada no elemento customizado de Markdown `<d-expandable>`.
+Blocos expansíveis recolhem conteúdo secundário atrás de um título clicável.
 
-Ele foi criado para conteúdo secundário que deve continuar disponível sem alongar o fluxo principal de leitura. O corpo mantém os mesmos recursos ricos de Markdown já usados nas seções da página, incluindo listas, blockquotes, blocos de código, diagramas Mermaid, tabelas, HTML bruto e quick links.
+Eles funcionam bem quando a seção principal precisa continuar curta, mas o leitor ainda pode precisar de detalhes opcionais, checklists, apêndices ou exemplos mais longos.
 
-## Props
-
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `title` | `String` | `''` | Rótulo do cabeçalho exibido no gatilho do expansível |
-| `open` | `Boolean` | `false` | Estado inicial expandido |
-
-## Slot
-
-O slot padrão recebe o corpo de conteúdo já parseado.
+O bloco é escrito com o custom element Markdown `<d-expandable>`.
 
 ## Exemplo em HTML
 

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

@@ -0,0 +1,45 @@
+## Overview
+
+Headings organize the reading flow and power the right-side table of contents.
+
+In Docsector, each body heading becomes a navigable anchor automatically using a GitHub-compatible slug, so readers can jump through the page while the URL hash and ToC stay in sync.
+
+## Markdown Levels
+
+| Markdown | HTML | Typical use |
+|----------|------|-------------|
+| `#` | `<h1>` | Page title generated from the page metadata |
+| `##` | `<h2>` | Main sections |
+| `###` | `<h3>` | Sub-sections |
+| `####` | `<h4>` | Detail sections |
+| `#####` | `<h5>` | Minor sections |
+| `######` | `<h6>` | Very small subdivisions |
+
+## Authoring Notes
+
+- In page content, the first heading you usually write is `##`, because the page title is already handled for you.
+- Keep heading levels in order whenever possible. Skipping levels makes the ToC harder to scan.
+- Use headings to break long pages into chunks that can be bookmarked, linked, and referenced from a standard Markdown Table of Contents.
+
+## What Docsector Handles
+
+- Registers headings as anchors in the page ToC
+- Uses GitHub-compatible slugs for heading hashes
+- Keeps navigation hashes aligned with the selected heading
+- Builds the section tree automatically from the Markdown structure
+
+## Markdown Example
+
+```markdown
+## Installation
+
+Short introduction.
+
+### Environment variables
+
+Extra setup details.
+
+#### Optional flags
+
+Notes for advanced readers.
+```

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

@@ -0,0 +1,45 @@
+## Visão Geral
+
+Títulos organizam o fluxo da leitura e alimentam o índice lateral da página.
+
+No Docsector, cada heading escrito no corpo do Markdown vira uma âncora navegável automaticamente usando slug compatível com GitHub, mantendo hash da URL e ToC sincronizados.
+
+## Níveis de Markdown
+
+| Markdown | HTML | Uso típico |
+|----------|------|------------|
+| `#` | `<h1>` | Título da página gerado a partir dos metadados |
+| `##` | `<h2>` | Seções principais |
+| `###` | `<h3>` | Sub-seções |
+| `####` | `<h4>` | Seções de detalhe |
+| `#####` | `<h5>` | Divisões menores |
+| `######` | `<h6>` | Divisões bem pequenas |
+
+## Notas de Autoria
+
+- No conteúdo da página, o primeiro heading costuma ser `##`, porque o título principal já é resolvido automaticamente.
+- Sempre que possível, mantenha a hierarquia em ordem. Pular níveis deixa o ToC mais difícil de ler.
+- Use títulos para quebrar páginas longas em partes que possam ser linkadas, revisitadas e referenciadas por um Table of Contents padrão de Markdown.
+
+## O Que o Docsector Faz
+
+- Registra os headings como âncoras no ToC da página
+- Usa slugs compatíveis com GitHub nos hashes dos headings
+- Mantém os hashes de navegação alinhados ao heading selecionado
+- Monta a árvore de seções automaticamente a partir da estrutura do Markdown
+
+## Exemplo em Markdown
+
+```markdown
+## Instalação
+
+Introdução curta.
+
+### Variáveis de ambiente
+
+Detalhes extras de setup.
+
+#### Flags opcionais
+
+Notas para leitores avançados.
+```

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

@@ -29,4 +29,4 @@ More content...
 Even more content...
 ```
 
-DPageSection automatically maps each heading level to the corresponding DH component.
+Docsector automatically maps each heading level to the right semantic heading and a matching ToC entry.

package/src/pages/manual/{components/d-headings.showcase.pt-BR.md → content/blocks/headings.showcase.pt-BR.md}

@@ -29,4 +29,4 @@ Mais conteúdo...
 Ainda mais conteúdo...
 ```
 
-DPageSection automaticamente mapeia cada nível de heading ao componente DH correspondente.
+O Docsector mapeia cada nível de heading para a marcação semântica correta e para a entrada correspondente no ToC.

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

@@ -0,0 +1,30 @@
+## Overview
+
+Hints are GitHub-style alert blocks rendered from Markdown blockquotes with a `[!TYPE]` marker.
+
+Use them when the content should be read as a note, tip, warning, or other semantic callout.
+
+For neutral quoted text without alert styling, see [Quote](/manual/content/blocks/quotes/overview/).
+
+## Markdown Syntax
+
+```markdown
+> [!WARNING]
+> This operation may interrupt workers.
+```
+
+## Supported Markers
+
+| Marker | When to use |
+|--------|-------------|
+| `NOTE` | Extra context or background |
+| `TIP` | Practical advice or best practice |
+| `IMPORTANT` | Critical information that must be noticed |
+| `WARNING` | Pitfalls, risky actions, or breaking changes |
+| `CAUTION` | High-risk actions that deserve extra care |
+
+## Notes
+
+- The marker should appear on the first line of the blockquote.
+- Hint bodies can still contain paragraphs, lists, code blocks, and math.
+- Unknown markers fall back to a regular quote.

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

@@ -0,0 +1,30 @@
+## Visão Geral
+
+Hints são blocos de alerta no estilo GitHub renderizados a partir de blockquotes Markdown com marcador `[!TYPE]`.
+
+Use esse bloco quando o conteúdo precisar ser lido como nota, dica, aviso ou outro callout semântico.
+
+Para texto citado de forma neutra, sem estilo de alerta, veja [Quote](/manual/content/blocks/quotes/overview/).
+
+## Sintaxe em Markdown
+
+```markdown
+> [!WARNING]
+> Esta operação pode interromper workers.
+```
+
+## Marcadores Suportados
+
+| Marcador | Quando usar |
+|----------|-------------|
+| `NOTE` | Contexto extra ou material de apoio |
+| `TIP` | Conselho prático ou boa prática |
+| `IMPORTANT` | Informação crítica que não pode passar despercebida |
+| `WARNING` | Armadilhas, ações arriscadas ou breaking changes |
+| `CAUTION` | Ações de alto risco que merecem cuidado extra |
+
+## Observações
+
+- O marcador deve aparecer na primeira linha do blockquote.
+- O corpo do hint ainda pode conter parágrafos, listas, blocos de código e matemática.
+- Marcadores desconhecidos voltam para o comportamento de uma citação comum.

package/src/pages/manual/content/blocks/hints.showcase.en-US.md

@@ -0,0 +1,30 @@
+## Showcase
+
+Hints render GitHub-style alert blockquotes directly in the reading flow.
+
+### Note
+
+> [!NOTE]
+> This is extra context that helps readers understand the current section.
+
+### Tip
+
+> [!TIP]
+> You can keep your examples short and focused to improve readability.
+
+### Important
+
+> [!IMPORTANT]
+> This migration changes defaults and must be reviewed before deployment.
+
+### Warning
+
+> [!WARNING]
+> This action may interrupt running workers in production.
+
+### Caution
+
+> [!CAUTION]
+> Back up your environment before applying this update.
+>
+> See `docs/migration.md` for the complete checklist.

package/src/pages/manual/content/blocks/hints.showcase.pt-BR.md

@@ -0,0 +1,30 @@
+## Demonstração
+
+Hints renderizam alertas no estilo GitHub diretamente no fluxo de leitura.
+
+### Note
+
+> [!NOTE]
+> Este é um contexto adicional que ajuda o leitor a entender a seção atual.
+
+### Tip
+
+> [!TIP]
+> Você pode manter os exemplos curtos e focados para melhorar a legibilidade.
+
+### Important
+
+> [!IMPORTANT]
+> Esta migração altera defaults e deve ser revisada antes do deploy.
+
+### Warning
+
+> [!WARNING]
+> Esta ação pode interromper workers em execução em produção.
+
+### Caution
+
+> [!CAUTION]
+> Faça backup do ambiente antes de aplicar esta atualização.
+>
+> Veja `docs/migration.md` para o checklist completo.

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

@@ -0,0 +1,16 @@
+## Overview
+
+Use standard Markdown images to place screenshots, illustrations, diagrams, and product UI directly inside the reading flow.
+
+## Markdown Syntax
+
+```markdown
+![Dashboard overview](/images/example-dashboard.png)
+```
+
+## Good Practices
+
+- Write descriptive alt text so the image still has meaning without the visual.
+- Prefer absolute site paths such as `/images/...` for assets stored in `public/images/`.
+- Use screenshots to support the text, not replace the explanation.
+- When default Markdown syntax is not enough, raw HTML can be used for custom wrappers or sizing.

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

@@ -0,0 +1,16 @@
+## Visão Geral
+
+Use imagens Markdown padrão para inserir screenshots, ilustrações, diagramas e interfaces diretamente no fluxo da leitura.
+
+## Sintaxe em Markdown
+
+```markdown
+![Visão geral do dashboard](/images/example-dashboard.png)
+```
+
+## Boas Práticas
+
+- Escreva um texto alternativo descritivo para que a imagem continue tendo significado sem o visual.
+- Prefira caminhos absolutos do site, como `/images/...`, para assets armazenados em `public/images/`.
+- Use screenshots para apoiar o texto, não para substituir a explicação.
+- Quando a sintaxe padrão de Markdown não for suficiente, use HTML bruto para wrappers ou tamanhos personalizados.

package/src/pages/manual/content/blocks/images.showcase.en-US.md

@@ -0,0 +1,11 @@
+## Showcase
+
+### Basic Image
+
+![Docsector Reader logo](/images/logo.png)
+
+### Image with Title
+
+![Docsector Reader logo](/images/logo.png "Docsector Reader")
+
+The alt text remains part of the content model, so the page still communicates meaning if the image cannot be seen.

package/src/pages/manual/content/blocks/images.showcase.pt-BR.md

@@ -0,0 +1,11 @@
+## Demonstração
+
+### Imagem Básica
+
+![Logo do Docsector Reader](/images/logo.png)
+
+### Imagem com Título
+
+![Logo do Docsector Reader](/images/logo.png "Docsector Reader")
+
+O texto alternativo continua fazendo parte do conteúdo, então a página ainda comunica significado mesmo quando a imagem não pode ser vista.