@docsector/docsector-reader 3.6.0 → 4.0.1

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

@@ -0,0 +1,115 @@
+## Showcase
+
+The examples below use the native vertical Quasar Stepper renderer. Click a step header or use the navigation buttons inside the active step.
+
+### Basic Setup Flow
+
+<d-block-stepper>
+  <d-block-step title="Install dependencies">
+
+Run `npm install` in the project root.
+
+  </d-block-step>
+
+  <d-block-step title="Start the development server">
+
+Run `npm run dev` and keep the terminal open while you work.
+
+  </d-block-step>
+
+  <d-block-step title="Open the app">
+
+Visit the local URL printed by the CLI and confirm the homepage loads.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Rich Markdown
+
+<d-block-stepper>
+  <d-block-step title="Check the prerequisites">
+
+- Node.js 20 or newer
+- npm 9 or newer
+- Access to the project repository
+
+  </d-block-step>
+
+  <d-block-step title="Run the smoke checks">
+
+> [!TIP]
+> Fix lint or test failures before opening a pull request.
+
+```bash
+npm run lint
+npm run test
+```
+
+  </d-block-step>
+
+  <d-block-step title="Capture the outcome">
+
+Attach the command output, note any warnings, and link the related issue or pull request.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Troubleshooting Sequence
+
+<d-block-stepper>
+  <d-block-step title="Reproduce the issue">
+
+Describe the exact page, browser, and action that triggered the problem.
+
+  </d-block-step>
+
+  <d-block-step title="Collect evidence">
+
+Take a screenshot, copy the console output, and note whether the issue also happens on mobile.
+
+  </d-block-step>
+
+  <d-block-step title="Validate the fix">
+
+Repeat the same flow after the change and confirm the original failure no longer appears.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Custom Header Icons
+
+<d-block-stepper>
+  <d-block-step title="Connect the repository" icon="folder_open" active-icon="folder_open" done-icon="task_alt">
+
+Clone the repository or open the existing local workspace before starting the workflow.
+
+  </d-block-step>
+
+  <d-block-step title="Review the issue" icon="manage_search" active-icon="manage_search" done-icon="task_alt">
+
+Read the reproduction steps, confirm the scope, and identify the narrowest possible fix.
+
+  </d-block-step>
+
+  <d-block-step title="Ship the patch" icon="rocket_launch" active-icon="rocket_launch" done-icon="verified">
+
+Run the focused checks, update the docs, and prepare the change for review.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Different Icons Per State
+
+<d-block-stepper>
+  <d-block-step title="Draft the plan" active-icon="edit_note" done-icon="task_alt">
+
+Keep the numeric prefix while the step is idle, then switch to a clearer icon while it is active or completed.
+
+  </d-block-step>
+
+  <d-block-step title="Validate the output" active-icon="play_circle" done-icon="check_circle">
+
+This pattern is useful when you want numbered headers by default but still want visual feedback during execution.
+
+  </d-block-step>
+</d-block-stepper>

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

@@ -0,0 +1,115 @@
+## Showcase
+
+Os exemplos abaixo usam o renderer nativo do Stepper vertical do Quasar. Clique no cabeçalho de uma etapa ou use os botões de navegação dentro da etapa ativa.
+
+### Fluxo básico de setup
+
+<d-block-stepper>
+  <d-block-step title="Instale as dependências">
+
+Execute `npm install` na raiz do projeto.
+
+  </d-block-step>
+
+  <d-block-step title="Inicie o servidor de desenvolvimento">
+
+Execute `npm run dev` e mantenha o terminal aberto durante o trabalho.
+
+  </d-block-step>
+
+  <d-block-step title="Abra a aplicação">
+
+Visite a URL local impressa pela CLI e confirme que a homepage foi carregada.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Markdown rico
+
+<d-block-stepper>
+  <d-block-step title="Confira os pré-requisitos">
+
+- Node.js 20 ou superior
+- npm 9 ou superior
+- Acesso ao repositório do projeto
+
+  </d-block-step>
+
+  <d-block-step title="Execute os smoke checks">
+
+> [!TIP]
+> Corrija falhas de lint ou teste antes de abrir um pull request.
+
+```bash
+npm run lint
+npm run test
+```
+
+  </d-block-step>
+
+  <d-block-step title="Registre o resultado">
+
+Anexe a saída dos comandos, documente warnings relevantes e adicione o link da issue ou do pull request relacionado.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Sequência de troubleshooting
+
+<d-block-stepper>
+  <d-block-step title="Reproduza o problema">
+
+Descreva exatamente a página, o navegador e a ação que dispararam o erro.
+
+  </d-block-step>
+
+  <d-block-step title="Colete evidências">
+
+Tire uma captura de tela, copie a saída do console e anote se o problema também acontece no mobile.
+
+  </d-block-step>
+
+  <d-block-step title="Valide a correção">
+
+Repita o mesmo fluxo depois da mudança e confirme que a falha original deixou de aparecer.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Ícones personalizados no cabeçalho
+
+<d-block-stepper>
+  <d-block-step title="Conecte o repositório" icon="folder_open" active-icon="folder_open" done-icon="task_alt">
+
+Clone o repositório ou abra o workspace local existente antes de começar o fluxo.
+
+  </d-block-step>
+
+  <d-block-step title="Revise a issue" icon="manage_search" active-icon="manage_search" done-icon="task_alt">
+
+Leia a reprodução, confirme o escopo e identifique a menor correção possível.
+
+  </d-block-step>
+
+  <d-block-step title="Entregue o patch" icon="rocket_launch" active-icon="rocket_launch" done-icon="verified">
+
+Execute os checks focados, atualize a documentação e prepare a mudança para revisão.
+
+  </d-block-step>
+</d-block-stepper>
+
+### Ícones diferentes por estado
+
+<d-block-stepper>
+  <d-block-step title="Esboce o plano" active-icon="edit_note" done-icon="task_alt">
+
+Mantenha a numeração enquanto a etapa está inativa e troque para um ícone mais claro quando ela estiver ativa ou concluída.
+
+  </d-block-step>
+
+  <d-block-step title="Valide a saída" active-icon="play_circle" done-icon="check_circle">
+
+Esse padrão é útil quando você quer cabeçalhos numerados por padrão, mas ainda deseja feedback visual durante a execução.
+
+  </d-block-step>
+</d-block-stepper>

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

@@ -0,0 +1,47 @@
+## Overview
+
+Timeline blocks render chronological updates inside Markdown, making them a good fit for changelogs, release notes, migration logs, and rollout journals.
+
+Each item requires a date, can expose optional tags, supports a stable hash anchor, and renders rich body content inside the entry.
+
+The block is authored with the custom Markdown elements `<d-block-timeline>`, `<d-block-timeline-item>`, and optional `<d-block-timeline-tag>` children.
+
+## HTML Example
+
+````html
+<d-block-timeline>
+  <d-block-timeline-item date="2025-12-25" anchor="brand-new-update">
+
+<d-block-timeline-tag color="warning" icon="rocket_launch">beta</d-block-timeline-tag>
+<d-block-timeline-tag color="secondary" text-color="white">docs</d-block-timeline-tag>
+
+## A brand new update
+
+Use this block for release notes, product announcements, migration notices, or operational updates.
+
+<d-block-quick-links title="Related links">
+  <d-block-quick-link title="Install" description="Set up the project" to="/guide/getting-started" />
+</d-block-quick-links>
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2026-01-10">
+
+## General availability
+
+This second entry gets its own generated anchor even when dates repeat.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+````
+
+## Notes
+
+- Every `<d-block-timeline-item>` must define a `date` attribute.
+- Timeline tags are optional and should be declared with `<d-block-timeline-tag>` inside the item body.
+- `<d-block-timeline-tag>` supports plain text content or a `label` attribute, plus optional `color`, `text-color`, and `icon` attributes.
+- `anchor` is optional. When omitted, Docsector generates a unique hash from the item date plus the first visible text block inside the item.
+- Item bodies support regular Markdown, alerts, fenced code, math, tables, images, and nested Docsector blocks that already work in normal page sections.
+- Headings inside timeline items are flattened into paragraph output so the page-level table of contents stays stable.
+- Timeline items do not add extra nodes to the right-side page TOC; deep links still work through normal hash URLs.
+- Keep a clear leading heading or paragraph near the top of each item so generated anchors stay readable.

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

@@ -0,0 +1,47 @@
+## Visão geral
+
+Os blocos Timeline renderizam atualizações cronológicas dentro do Markdown, sendo uma boa escolha para changelogs, notas de versão, históricos de migração e diários de rollout.
+
+Cada item exige uma data, pode expor tags opcionais, aceita uma âncora estável e renderiza conteúdo rico dentro da entrada.
+
+O bloco é escrito com os elementos Markdown customizados `<d-block-timeline>`, `<d-block-timeline-item>` e os filhos opcionais `<d-block-timeline-tag>`.
+
+## Exemplo em HTML
+
+````html
+<d-block-timeline>
+  <d-block-timeline-item date="2025-12-25" anchor="brand-new-update">
+
+<d-block-timeline-tag color="warning" icon="rocket_launch">beta</d-block-timeline-tag>
+<d-block-timeline-tag color="secondary" text-color="white">docs</d-block-timeline-tag>
+
+## Uma atualização novinha
+
+Use este bloco para notas de versão, anúncios de produto, avisos de migração ou atualizações operacionais.
+
+<d-block-quick-links title="Links relacionados">
+  <d-block-quick-link title="Instalar" description="Prepare o projeto" to="/guide/getting-started" />
+</d-block-quick-links>
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2026-01-10">
+
+## Disponibilidade geral
+
+Esta segunda entrada recebe sua própria âncora gerada automaticamente, mesmo quando datas se repetem.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+````
+
+## Observações
+
+- Todo `<d-block-timeline-item>` precisa definir o atributo `date`.
+- As tags do timeline são opcionais e devem ser declaradas com `<d-block-timeline-tag>` dentro do corpo do item.
+- `<d-block-timeline-tag>` aceita texto simples ou um atributo `label`, além de `color`, `text-color` e `icon` opcionais.
+- `anchor` é opcional. Quando omitido, o Docsector gera um hash único a partir da data do item e do primeiro bloco de texto visível dentro da entrada.
+- O corpo do item suporta Markdown comum, alertas, blocos de código, matemática, tabelas, imagens e blocos Docsector aninhados que já funcionam em seções normais da página.
+- Títulos dentro dos itens são achatados para saída de parágrafo, para manter estável o sumário principal da página.
+- Itens de Timeline não adicionam novos nós ao sumário lateral; links profundos continuam funcionando com hashes normais.
+- Mantenha um título ou parágrafo inicial claro no topo de cada item para que as âncoras geradas fiquem legíveis.

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

@@ -0,0 +1,170 @@
+## Showcase
+
+The examples below show changelog-style timelines with rich content, tags, repeated dates, and direct-link anchors.
+
+### Long scrolling content with multiple entries
+
+<d-block-timeline>
+  <d-block-timeline-item date="2025-12-18">
+
+<d-block-timeline-tag color="warning" icon="rocket_launch">release</d-block-timeline-tag>
+<d-block-timeline-tag color="secondary" text-color="white">migration</d-block-timeline-tag>
+
+## Migration preparation
+
+Start by documenting the exact scope of the rollout, including the pages, integrations, and deployment windows that are affected by the change.
+
+Create a short checklist for the team, then confirm which parts of the rollout can happen in parallel and which ones must stay serialized.
+
+- Confirm the affected environments
+- Capture rollback steps
+- Note any user-facing communication that must ship together with the release
+
+~~~bash
+npm run lint
+npm run test
+npm run build
+~~~
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2025-12-19">
+
+<d-block-timeline-tag color="primary" text-color="white">operations</d-block-timeline-tag>
+<d-block-timeline-tag color="orange" text-color="white">rollout</d-block-timeline-tag>
+
+## Incremental rollout
+
+Ship the first slice to a smaller audience, watch the error budget, and log any unexpected behavior before widening exposure.
+
+If the metrics remain healthy, continue with the second rollout wave and update the changelog entry with the exact time and the observed result.
+
+> [!TIP]
+> Sticky dates and dots are easier to verify when each item contains enough body content to scroll independently.
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2025-12-20">
+
+<d-block-timeline-tag color="teal" text-color="white">follow-up</d-block-timeline-tag>
+<d-block-timeline-tag color="grey-8" text-color="white">docs</d-block-timeline-tag>
+
+## Post-release follow-up
+
+After the rollout finishes, collect the final metrics, summarize what changed, and add links to the support article, incident notes, or migration guide.
+
+This entry is intentionally long enough to help verify the comfortable-layout sticky behavior on later timeline items, not only on the first one.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Single long entry
+
+<d-block-timeline>
+  <d-block-timeline-item date="2025-11-30">
+
+<d-block-timeline-tag color="brown-5" text-color="white">single</d-block-timeline-tag>
+<d-block-timeline-tag color="indigo" text-color="white" icon="push_pin">sticky-check</d-block-timeline-tag>
+
+## One long entry for sticky checks
+
+Use a single-item timeline when you want to confirm that the date and dot still stick correctly even without later entries extending the rail.
+
+Repeat enough explanatory content here to create real scroll distance for the item and confirm the left-side metadata remains visible while the body moves.
+
+Repeat enough explanatory content here to create real scroll distance for the item and confirm the left-side metadata remains visible while the body moves.
+
+Repeat enough explanatory content here to create real scroll distance for the item and confirm the left-side metadata remains visible while the body moves.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Product updates
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-05-07">
+
+<d-block-timeline-tag color="warning" icon="campaign">release</d-block-timeline-tag>
+<d-block-timeline-tag color="amber-8" text-color="white">permissions</d-block-timeline-tag>
+
+## Site permissions update
+
+We simplified inheritance so site-level permissions are now easier to reason about across linked content.
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2026-04-28">
+
+<d-block-timeline-tag color="positive" text-color="white">improvement</d-block-timeline-tag>
+<d-block-timeline-tag color="primary" text-color="white" icon="search">search</d-block-timeline-tag>
+
+## Faster site search
+
+Readers now get faster results from a local index, followed by remote refinement when more matches arrive.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Rich markdown inside entries
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-03-04">
+
+<d-block-timeline-tag color="warning" icon="science">beta</d-block-timeline-tag>
+<d-block-timeline-tag color="deep-orange" text-color="white">rss</d-block-timeline-tag>
+
+## Update blocks with RSS support
+
+> [!TIP]
+> Use tags to label beta or rollout-specific entries.
+
+~~~bash
+npm run build
+npm run release
+~~~
+
+<d-block-quick-links title="Related links">
+  <d-block-quick-link title="Guide" description="Open the getting started guide" to="/guide/getting-started" />
+  <d-block-quick-link title="Repository" description="View the source code" href="https://github.com/docsector/docsector-reader" icon="launch" />
+</d-block-quick-links>
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Explicit anchors
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-02-11" anchor="custom-icons-release">
+
+<d-block-timeline-tag color="purple" text-color="white" icon="palette">ux</d-block-timeline-tag>
+
+## Custom icons in hint blocks
+
+Use the `anchor` attribute when you want a stable fragment that does not depend on the visible title copy.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Repeated dates with unique generated anchors
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-01-05">
+
+<d-block-timeline-tag color="positive" text-color="white">improvement</d-block-timeline-tag>
+
+## New year improvements
+
+Generated anchors stay unique even if another item reuses the same date and title.
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2026-01-05">
+
+<d-block-timeline-tag color="negative" text-color="white">fixes</d-block-timeline-tag>
+
+## New year improvements
+
+This second entry gets a deduplicated hash suffix automatically.
+
+  </d-block-timeline-item>
+</d-block-timeline>

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

@@ -0,0 +1,170 @@
+## Showcase
+
+Os exemplos abaixo mostram timelines no estilo changelog com conteúdo rico, tags, datas repetidas e âncoras diretas.
+
+### Conteúdo longo com múltiplas entradas
+
+<d-block-timeline>
+  <d-block-timeline-item date="2025-12-18">
+
+<d-block-timeline-tag color="warning" icon="rocket_launch">release</d-block-timeline-tag>
+<d-block-timeline-tag color="secondary" text-color="white">migração</d-block-timeline-tag>
+
+## Preparação da migração
+
+Comece documentando o escopo exato do rollout, incluindo as páginas, integrações e janelas de deploy afetadas pela mudança.
+
+Crie uma checklist curta para o time e depois confirme quais partes do rollout podem acontecer em paralelo e quais precisam permanecer serializadas.
+
+- Confirmar os ambientes afetados
+- Registrar os passos de rollback
+- Anotar qualquer comunicação ao usuário que precise sair junto com o release
+
+~~~bash
+npm run lint
+npm run test
+npm run build
+~~~
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2025-12-19">
+
+<d-block-timeline-tag color="primary" text-color="white">operações</d-block-timeline-tag>
+<d-block-timeline-tag color="orange" text-color="white">rollout</d-block-timeline-tag>
+
+## Rollout incremental
+
+Envie a primeira fatia para uma audiência menor, acompanhe o orçamento de erros e registre qualquer comportamento inesperado antes de ampliar a exposição.
+
+Se as métricas continuarem saudáveis, avance para a segunda onda do rollout e atualize a entrada do changelog com o horário exato e o resultado observado.
+
+> [!TIP]
+> Datas e dots sticky ficam mais fáceis de validar quando cada item tem conteúdo suficiente para rolar de forma independente.
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2025-12-20">
+
+<d-block-timeline-tag color="teal" text-color="white">follow-up</d-block-timeline-tag>
+<d-block-timeline-tag color="grey-8" text-color="white">docs</d-block-timeline-tag>
+
+## Acompanhamento pós-release
+
+Depois que o rollout terminar, colete as métricas finais, resuma o que mudou e adicione links para o artigo de suporte, notas de incidente ou guia de migração.
+
+Esta entrada foi deixada propositalmente longa para ajudar a verificar o comportamento sticky do layout confortável também nos itens posteriores, não apenas no primeiro.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Entrada única longa
+
+<d-block-timeline>
+  <d-block-timeline-item date="2025-11-30">
+
+<d-block-timeline-tag color="brown-5" text-color="white">único</d-block-timeline-tag>
+<d-block-timeline-tag color="indigo" text-color="white" icon="push_pin">sticky-check</d-block-timeline-tag>
+
+## Uma entrada longa para validar sticky
+
+Use um timeline com item único quando quiser confirmar que a data e o dot continuam sticky corretamente mesmo sem outras entradas posteriores estendendo a trilha.
+
+Repita conteúdo explicativo suficiente aqui para criar distância real de scroll dentro do item e confirmar que os metadados do lado esquerdo continuam visíveis enquanto o corpo se move.
+
+Repita conteúdo explicativo suficiente aqui para criar distância real de scroll dentro do item e confirmar que os metadados do lado esquerdo continuam visíveis enquanto o corpo se move.
+
+Repita conteúdo explicativo suficiente aqui para criar distância real de scroll dentro do item e confirmar que os metadados do lado esquerdo continuam visíveis enquanto o corpo se move.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Atualizações de produto
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-05-07">
+
+<d-block-timeline-tag color="warning" icon="campaign">release</d-block-timeline-tag>
+<d-block-timeline-tag color="amber-8" text-color="white">permissões</d-block-timeline-tag>
+
+## Atualização nas permissões do site
+
+Simplificamos a herança para que as permissões no nível do site fiquem mais fáceis de entender em conteúdos vinculados.
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2026-04-28">
+
+<d-block-timeline-tag color="positive" text-color="white">melhoria</d-block-timeline-tag>
+<d-block-timeline-tag color="primary" text-color="white" icon="search">busca</d-block-timeline-tag>
+
+## Busca do site mais rápida
+
+Leitores agora recebem resultados mais rápidos a partir de um índice local, seguidos por refinamento remoto quando novas correspondências aparecem.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Markdown rico dentro das entradas
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-03-04">
+
+<d-block-timeline-tag color="warning" icon="science">beta</d-block-timeline-tag>
+<d-block-timeline-tag color="deep-orange" text-color="white">rss</d-block-timeline-tag>
+
+## Blocos de update com suporte a RSS
+
+> [!TIP]
+> Use tags para marcar entradas beta ou específicas de rollout.
+
+~~~bash
+npm run build
+npm run release
+~~~
+
+<d-block-quick-links title="Links relacionados">
+  <d-block-quick-link title="Guia" description="Abra o guia de introdução" to="/guide/getting-started" />
+  <d-block-quick-link title="Repositório" description="Veja o código-fonte" href="https://github.com/docsector/docsector-reader" icon="launch" />
+</d-block-quick-links>
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Âncoras explícitas
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-02-11" anchor="custom-icons-release">
+
+<d-block-timeline-tag color="purple" text-color="white" icon="palette">ux</d-block-timeline-tag>
+
+## Ícones customizados em hint blocks
+
+Use o atributo `anchor` quando quiser um fragmento estável que não dependa do texto visível do título.
+
+  </d-block-timeline-item>
+</d-block-timeline>
+
+### Datas repetidas com âncoras geradas únicas
+
+<d-block-timeline>
+  <d-block-timeline-item date="2026-01-05">
+
+<d-block-timeline-tag color="positive" text-color="white">melhoria</d-block-timeline-tag>
+
+## Melhorias de ano novo
+
+Âncoras geradas continuam únicas mesmo quando outra entrada reutiliza a mesma data e o mesmo título.
+
+  </d-block-timeline-item>
+
+  <d-block-timeline-item date="2026-01-05">
+
+<d-block-timeline-tag color="negative" text-color="white">correções</d-block-timeline-tag>
+
+## Melhorias de ano novo
+
+Esta segunda entrada recebe automaticamente um sufixo deduplicado no hash.
+
+  </d-block-timeline-item>
+</d-block-timeline>