@docsector/docsector-reader 3.1.0 → 3.2.1

package/src/pages/manual/content/blocks/math-and-tex.overview.en-US.md

@@ -0,0 +1,27 @@
+## Overview
+
+Math and TeX support lets you write inline equations and display formulas directly in Markdown using KaTeX-compatible syntax.
+
+## Inline Math
+
+Use single dollar delimiters inside normal text:
+
+```markdown
+Use $E = mc^2$ inside a sentence.
+```
+
+## Display Math
+
+Use double dollar delimiters for standalone formulas:
+
+```markdown
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+## Notes
+
+- Math works in paragraphs, hints, and expandable blocks.
+- Delimiters remain literal inside inline code and fenced code blocks.
+- Use display math when the formula needs its own visual space.

package/src/pages/manual/content/blocks/math-and-tex.overview.pt-BR.md

@@ -0,0 +1,27 @@
+## Visão Geral
+
+O suporte a Math e TeX permite escrever equações inline e fórmulas destacadas diretamente no Markdown usando sintaxe compatível com KaTeX.
+
+## Matemática Inline
+
+Use delimitadores com um único cifrão dentro do texto normal:
+
+```markdown
+Use $E = mc^2$ dentro de uma frase.
+```
+
+## Matemática em Bloco
+
+Use delimitadores com dois cifrões para fórmulas em destaque:
+
+```markdown
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+## Observações
+
+- Matemática funciona em parágrafos, hints e blocos expansíveis.
+- Os delimitadores continuam literais dentro de código inline e blocos de código cercados.
+- Use matemática em bloco quando a fórmula precisar de espaço visual próprio.

package/src/pages/manual/content/blocks/math-and-tex.showcase.en-US.md

@@ -0,0 +1,14 @@
+## Showcase
+
+Inline math works inside normal prose, such as $a^2 + b^2 = c^2$.
+
+### Display Formula
+
+$$
+x^2 + y^2 = z^2
+$$
+
+### Math Inside a Hint
+
+> [!IMPORTANT]
+> This growth rule uses $f(x) = x^2 + 2x + 1$ in the documentation text itself.

package/src/pages/manual/content/blocks/math-and-tex.showcase.pt-BR.md

@@ -0,0 +1,14 @@
+## Demonstração
+
+Matemática inline funciona dentro do texto normal, como em $a^2 + b^2 = c^2$.
+
+### Fórmula em Destaque
+
+$$
+x^2 + y^2 = z^2
+$$
+
+### Matemática Dentro de um Hint
+
+> [!IMPORTANT]
+> Esta regra de crescimento usa $f(x) = x^2 + 2x + 1$ dentro do próprio texto da documentação.

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

@@ -0,0 +1,22 @@
+## Overview
+
+Mermaid diagrams are authored with fenced code blocks that use the `mermaid` language identifier.
+
+Docsector turns those definitions into responsive SVG diagrams directly inside the page, so flowcharts, sequence diagrams, and similar visuals can live next to the written explanation.
+
+## Basic Syntax
+
+````markdown
+```mermaid
+flowchart TD
+	A[Start] --> B[Finish]
+```
+````
+
+## What Docsector Handles
+
+- Lazy-loads Mermaid only when a page actually contains a diagram
+- Renders diagrams as responsive SVG output
+- Rebuilds the diagram when the reader switches between light and dark mode
+- Shows a safe error state if the Mermaid syntax is invalid
+- Decodes `{` and `}` before rendering so i18n-safe source still works

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

@@ -0,0 +1,22 @@
+## Visão Geral
+
+Diagramas Mermaid são escritos com fences de código usando o identificador de linguagem `mermaid`.
+
+O Docsector transforma essas definições em SVGs responsivos dentro da própria página, permitindo documentar fluxos, sequências e outros diagramas lado a lado com a explicação em texto.
+
+## Sintaxe Básica
+
+````markdown
+```mermaid
+flowchart TD
+	A[Início] --> B[Fim]
+```
+````
+
+## O Que o Docsector Faz
+
+- Carrega o Mermaid sob demanda, apenas quando a página realmente contém diagramas
+- Renderiza a saída como SVG responsivo
+- Reconstrói o diagrama quando o leitor alterna entre modo claro e escuro
+- Mostra um estado de erro seguro se a sintaxe Mermaid estiver inválida
+- Decodifica `{` e `}` antes da renderização para manter compatibilidade com conteúdo seguro para i18n

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

@@ -0,0 +1,19 @@
+## Overview
+
+Use ordered lists when the sequence of the items matters.
+
+They are a good fit for installation steps, review checklists, migrations, or any process the reader should follow in order.
+
+## Markdown Syntax
+
+```markdown
+1. Install dependencies
+2. Start the dev server
+3. Open the documentation site
+```
+
+## Notes
+
+- Ordered lists communicate progression or priority.
+- Nested ordered lists work the same way as nested bullet lists.
+- Keep each item concise when the list represents a procedure.

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

@@ -0,0 +1,19 @@
+## Visão Geral
+
+Use listas ordenadas quando a sequência dos itens importa.
+
+Elas são ideais para passos de instalação, checklists de revisão, migrações ou qualquer processo que o leitor deva seguir em ordem.
+
+## Sintaxe em Markdown
+
+```markdown
+1. Instale as dependências
+2. Inicie o servidor de desenvolvimento
+3. Abra o site de documentação
+```
+
+## Observações
+
+- Listas ordenadas comunicam progressão ou prioridade.
+- Listas ordenadas aninhadas funcionam da mesma forma que listas com marcadores aninhadas.
+- Quando a lista representa um procedimento, mantenha cada item direto ao ponto.

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

@@ -0,0 +1,21 @@
+## Showcase
+
+### Sequential Steps
+
+1. Create the page entry in the registry.
+2. Write the localized overview markdown.
+3. Add a showcase page with real examples.
+4. Run tests and the build.
+
+### Nested Sequence
+
+1. Prepare the change.
+   1. Confirm the route path.
+   2. Check the required markdown files.
+2. Validate the result.
+   1. Run the focused tests.
+   2. Build the site.
+
+### When Ordered Lists Fit Best
+
+Use numbered lists when the reader should follow a procedure, a checklist, or a lifecycle in a specific order.

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

@@ -0,0 +1,21 @@
+## Demonstração
+
+### Etapas Sequenciais
+
+1. Crie a entrada da página no registry.
+2. Escreva o markdown de overview localizado.
+3. Adicione uma página de showcase com exemplos reais.
+4. Rode os testes e o build.
+
+### Sequência Aninhada
+
+1. Prepare a mudança.
+   1. Confirme o caminho da rota.
+   2. Verifique os arquivos Markdown necessários.
+2. Valide o resultado.
+   1. Rode os testes focados.
+   2. Gere o build do site.
+
+### Quando Listas Ordenadas Funcionam Melhor
+
+Use listas numeradas quando o leitor precisa seguir um procedimento, checklist ou fluxo em uma ordem específica.

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

@@ -0,0 +1,19 @@
+## Overview
+
+Paragraphs are the default block for narrative text.
+
+Use them for explanations, transitions between sections, introductions before lists or code, and any copy that should read as a continuous flow.
+
+## Markdown Syntax
+
+```markdown
+This is the first paragraph with **bold text**, _emphasis_, a [link](/guide/getting-started/overview/), and `inline code`.
+
+This is a second paragraph separated by a blank line.
+```
+
+## Notes
+
+- Start a new paragraph with a blank line.
+- Inline formatting such as emphasis, links, code, and math works inside normal paragraphs.
+- Keep each paragraph focused on one idea when the page is long.

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

@@ -0,0 +1,19 @@
+## Visão Geral
+
+Parágrafos são o bloco padrão para texto corrido.
+
+Use-os para explicações, transições entre seções, introduções antes de listas ou código e qualquer conteúdo que deva ser lido como um fluxo contínuo.
+
+## Sintaxe em Markdown
+
+```markdown
+Este é o primeiro parágrafo com **negrito**, _ênfase_, um [link](/guide/getting-started/overview/) e `código inline`.
+
+Este é um segundo parágrafo separado por uma linha em branco.
+```
+
+## Observações
+
+- Comece um novo parágrafo com uma linha em branco.
+- Formatações inline como ênfase, links, código e matemática funcionam dentro de parágrafos normais.
+- Em páginas longas, mantenha cada parágrafo focado em uma única ideia.

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

@@ -0,0 +1,9 @@
+## Showcase
+
+Paragraphs are where most of the narrative work happens in a documentation page. They carry explanations, transitions, and the details that connect examples to decisions.
+
+This second paragraph is separated by a blank line, which is all Markdown needs to start a new block. Inline formatting such as **bold text**, _emphasis_, [links](/guide/getting-started/overview/), and `inline code` all remain available inside the paragraph flow.
+
+### Reading Rhythm
+
+Short paragraphs keep scanning easy. Longer paragraphs work well when you need to explain tradeoffs, migration notes, or the reasoning behind a recommendation.

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

@@ -0,0 +1,9 @@
+## Demonstração
+
+Parágrafos são onde a maior parte do trabalho narrativo acontece em uma página de documentação. Eles carregam explicações, transições e os detalhes que conectam exemplos a decisões.
+
+Este segundo parágrafo é separado por uma linha em branco, que é tudo o que o Markdown precisa para iniciar um novo bloco. Formatações inline como **negrito**, _ênfase_, [links](/guide/getting-started/overview/) e `inline code` continuam disponíveis dentro do fluxo do parágrafo.
+
+### Ritmo de Leitura
+
+Parágrafos curtos facilitam a varredura visual. Parágrafos mais longos funcionam bem quando você precisa explicar tradeoffs, notas de migração ou o motivo por trás de uma recomendação.

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

@@ -0,0 +1,28 @@
+## Overview
+
+Quick Links render a card-like list of internal or external destinations directly inside Markdown.
+
+They are useful for homepages, landing sections, and any page that should offer clear next steps without writing a long list of prose links.
+
+## Markdown Syntax
+
+```html
+<d-quick-links title="Get started">
+  <d-quick-link
+    title="Install"
+    description="Set up the project"
+    to="/guide/getting-started"
+  />
+  <d-quick-link
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+  />
+</d-quick-links>
+```
+
+## Notes
+
+- Use `to` for internal navigation and `href` for external URLs.
+- Add short descriptions so the cards explain why the destination matters.
+- Use a small set of links per group to keep scanning easy.

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

@@ -0,0 +1,28 @@
+## Visão Geral
+
+Quick Links renderizam uma lista de destinos internos ou externos em formato de cards diretamente no Markdown.
+
+Eles são úteis para homepages, seções de entrada e qualquer página que precise oferecer próximos passos claros sem depender de uma longa lista de links em prosa.
+
+## Sintaxe em Markdown
+
+```html
+<d-quick-links title="Comece aqui">
+  <d-quick-link
+    title="Instalação"
+    description="Configure o projeto"
+    to="/guide/getting-started"
+  />
+  <d-quick-link
+    title="GitHub"
+    description="Abra o repositório"
+    href="https://github.com/docsector/docsector-reader"
+  />
+</d-quick-links>
+```
+
+## Observações
+
+- Use `to` para navegação interna e `href` para URLs externas.
+- Adicione descrições curtas para que os cards expliquem por que o destino importa.
+- Use poucos links por grupo para manter a leitura fácil.

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

@@ -0,0 +1,34 @@
+## Showcase
+
+<d-quick-links title="Continue reading">
+  <d-quick-link
+    title="Getting Started"
+    description="Install and run the project"
+    to="/guide/getting-started"
+  />
+  <d-quick-link
+    title="Headings"
+    description="Open a block example with showcase"
+    to="/manual/content/blocks/headings"
+  />
+  <d-quick-link
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+  />
+</d-quick-links>
+
+## Smaller Group
+
+<d-quick-links title="Next actions">
+  <d-quick-link
+    title="Page structure"
+    description="Read the page container overview"
+    to="/manual/content/structures/page"
+  />
+  <d-quick-link
+    title="Quick Links overview"
+    description="Return to the reference page"
+    to="/manual/content/blocks/quick-links"
+  />
+</d-quick-links>

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

@@ -0,0 +1,34 @@
+## Demonstração
+
+<d-quick-links title="Continue lendo">
+  <d-quick-link
+    title="Começando"
+    description="Instale e rode o projeto"
+    to="/guide/getting-started"
+  />
+  <d-quick-link
+    title="Títulos"
+    description="Abra um exemplo de bloco com showcase"
+    to="/manual/content/blocks/headings"
+  />
+  <d-quick-link
+    title="GitHub"
+    description="Abra o repositório"
+    href="https://github.com/docsector/docsector-reader"
+  />
+</d-quick-links>
+
+## Grupo Menor
+
+<d-quick-links title="Próximas ações">
+  <d-quick-link
+    title="Estrutura de página"
+    description="Leia o overview do container de page"
+    to="/manual/content/structures/page"
+  />
+  <d-quick-link
+    title="Overview de Quick Links"
+    description="Volte para a página de referência"
+    to="/manual/content/blocks/quick-links"
+  />
+</d-quick-links>

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

@@ -0,0 +1,24 @@
+## Overview
+
+Quotes render regular blockquotes without alert styling.
+
+Use them for cited text, quoted excerpts, or offset notes that should stand apart from the main paragraph flow without looking like a warning or a callout.
+
+For alert-style blocks such as Note, Tip, Important, Warning, and Caution, see [Hints](/manual/content/blocks/hints/overview/).
+
+## Markdown Syntax
+
+```markdown
+> This is a regular quote.
+```
+
+## Good Uses
+
+- Quoted speech or copied excerpts
+- Short citations from guides, specs, or changelogs
+- Side notes that need visual separation but not semantic severity
+
+## Notes
+
+- If there is no `[!TYPE]` marker, Docsector keeps the blockquote neutral.
+- Regular quotes can still contain inline emphasis, links, inline code, and math.

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

@@ -0,0 +1,24 @@
+## Visão Geral
+
+Citações renderizam blockquotes comuns, sem estilo de alerta.
+
+Use esse bloco para trechos citados, excertos destacados ou notas laterais que precisam se separar visualmente do texto principal sem parecer um aviso ou callout semântico.
+
+Para blocos de alerta como Note, Tip, Important, Warning e Caution, veja [Hints](/manual/content/blocks/hints/overview/).
+
+## Sintaxe em Markdown
+
+```markdown
+> Esta é uma citação comum.
+```
+
+## Bons Usos
+
+- Fala citada ou trechos copiados
+- Pequenas citações de guias, specs ou changelogs
+- Notas laterais que pedem destaque visual, mas não severidade semântica
+
+## Observações
+
+- Se não houver marcador `[!TYPE]`, o Docsector mantém o blockquote em modo neutro.
+- Citações comuns ainda podem conter ênfase inline, links, código inline e matemática.

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

@@ -0,0 +1,17 @@
+## Showcase
+
+### Single Paragraph Quote
+
+> Documentation becomes easier to maintain when examples stay close to the behavior they describe.
+
+### Multi-Paragraph Quote
+
+> A regular quote can span more than one paragraph.
+>
+> Blank lines are preserved inside the blockquote, so the reader can still distinguish separate ideas.
+
+### Rich Quote Content
+
+> Quotes still support **bold text**, [links](https://github.com/docsector/docsector-reader), and `inline code`.
+>
+> They work well for cited text, pull quotes, or neutral callouts that should not use alert styling.

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

@@ -0,0 +1,17 @@
+## Demonstração
+
+### Citação com Um Parágrafo
+
+> A documentação fica mais fácil de manter quando os exemplos ficam próximos do comportamento que descrevem.
+
+### Citação com Múltiplos Parágrafos
+
+> Uma citação comum pode se estender por mais de um parágrafo.
+>
+> Linhas em branco são preservadas dentro do blockquote, então o leitor ainda consegue distinguir ideias separadas.
+
+### Conteúdo Rico na Citação
+
+> Citações continuam suportando **negrito**, [links](https://github.com/docsector/docsector-reader) e `inline code`.
+>
+> Elas funcionam bem para texto citado, pull quotes ou callouts neutros que não devem usar estilo de alerta.

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

@@ -0,0 +1,19 @@
+## Overview
+
+Raw HTML can be used inside Markdown when the native Markdown syntax is not expressive enough.
+
+This is useful for custom wrappers, inline labels, embedded elements, and Docsector-specific custom elements such as expandable blocks and quick links.
+
+## Markdown Example
+
+```html
+<div data-kind="secondary-note">
+  This block uses raw HTML inside the page source.
+</div>
+```
+
+## Notes
+
+- Prefer plain Markdown first when it already solves the problem.
+- Use raw HTML when you need structure or attributes that Markdown does not provide.
+- Keep the markup readable, because documentation content still needs to be maintained by humans.

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

@@ -0,0 +1,19 @@
+## Visão Geral
+
+HTML bruto pode ser usado dentro do Markdown quando a sintaxe nativa de Markdown não é expressiva o suficiente.
+
+Isso é útil para wrappers customizados, labels inline, elementos embutidos e custom elements do Docsector, como blocos expansíveis e quick links.
+
+## Exemplo em Markdown
+
+```html
+<div data-kind="secondary-note">
+  Este bloco usa HTML bruto dentro do conteúdo da página.
+</div>
+```
+
+## Observações
+
+- Prefira Markdown puro primeiro quando ele já resolver o problema.
+- Use HTML bruto quando precisar de estrutura ou atributos que o Markdown não oferece.
+- Mantenha a marcação legível, porque o conteúdo da documentação ainda precisa ser mantido por pessoas.

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

@@ -0,0 +1,12 @@
+## Showcase
+
+### Custom Wrapper
+
+<div style="padding: 1rem; border: 1px solid currentColor; border-radius: 12px; margin-bottom: 1rem;">
+  <strong>Custom note</strong><br />
+  This example uses raw HTML when plain Markdown is not expressive enough.
+</div>
+
+### Inline Badge
+
+Use <span style="padding: 0.15rem 0.45rem; border: 1px solid currentColor; border-radius: 999px;">beta</span> labels directly inside a sentence.

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

@@ -0,0 +1,12 @@
+## Demonstração
+
+### Wrapper Customizado
+
+<div style="padding: 1rem; border: 1px solid currentColor; border-radius: 12px; margin-bottom: 1rem;">
+  <strong>Nota customizada</strong><br />
+  Este exemplo usa HTML bruto quando o Markdown puro não é expressivo o suficiente.
+</div>
+
+### Badge Inline
+
+Use selos <span style="padding: 0.15rem 0.45rem; border: 1px solid currentColor; border-radius: 999px;">beta</span> diretamente dentro de uma frase.

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

@@ -0,0 +1,19 @@
+## Overview
+
+Tables are useful for comparisons, option matrices, compatibility notes, and any content that benefits from a row-and-column layout.
+
+## Markdown Syntax
+
+```markdown
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Search | Done | Available in the sidebar |
+| Math | Done | Rendered with KaTeX |
+| Mermaid | Done | Theme-aware diagrams |
+```
+
+## Notes
+
+- Keep column labels short and clear.
+- Use tables when scanning is more important than narrative flow.
+- If the content becomes too dense, split it into multiple smaller tables.

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

@@ -0,0 +1,19 @@
+## Visão Geral
+
+Tabelas são úteis para comparações, matrizes de opções, notas de compatibilidade e qualquer conteúdo que se beneficie de um layout em linhas e colunas.
+
+## Sintaxe em Markdown
+
+```markdown
+| Recurso | Status | Observações |
+|---------|--------|-------------|
+| Busca | Done | Disponível na sidebar |
+| Math | Done | Renderizado com KaTeX |
+| Mermaid | Done | Diagramas adaptados ao tema |
+```
+
+## Observações
+
+- Mantenha os rótulos das colunas curtos e claros.
+- Use tabelas quando a leitura em modo de varredura for mais importante que o fluxo narrativo.
+- Se o conteúdo ficar denso demais, quebre em várias tabelas menores.

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

@@ -0,0 +1,17 @@
+## Showcase
+
+### Feature Matrix
+
+| Block | Showcase | Best for |
+|-------|----------|----------|
+| Paragraphs | Yes | Narrative explanations |
+| Code blocks | Yes | Technical examples |
+| Quick Links | Yes | Guided navigation |
+
+### Alignment Example
+
+| Left | Center | Right |
+|:-----|:------:|------:|
+| Label | Status | 3 |
+| Blocks | Ready | 14 |
+| Structures | Focused | 3 |

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

@@ -0,0 +1,17 @@
+## Demonstração
+
+### Matriz de Recursos
+
+| Bloco | Showcase | Melhor uso |
+|-------|----------|-------------|
+| Parágrafos | Sim | Explicações narrativas |
+| Blocos de código | Sim | Exemplos técnicos |
+| Quick Links | Sim | Navegação guiada |
+
+### Exemplo de Alinhamento
+
+| Esquerda | Centro | Direita |
+|:---------|:------:|--------:|
+| Rótulo | Status | 3 |
+| Blocos | Pronto | 14 |
+| Estruturas | Focado | 3 |

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

@@ -0,0 +1,21 @@
+## Overview
+
+Use unordered lists when the order of the items does not matter.
+
+They work well for feature sets, requirements, grouped notes, and short collections of related points.
+
+## Markdown Syntax
+
+```markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+```
+
+## Notes
+
+- `-`, `*`, and `+` are all valid bullet markers.
+- Indent nested items to create sublists.
+- Use unordered lists for collections, not for step-by-step procedures.