@docsector/docsector-reader 2.2.0 → 3.0.0

package/src/pages/guide/getting-started.overview.en-US.md

@@ -64,7 +64,7 @@ After `init`, your project will have this structure:
 - `src/pages/guide/` — Guide-type pages (Markdown files)
 - `src/pages/manual/` — Manual-type pages (Markdown files)
 - `src/i18n/index.js` — i18n loader using `buildMessages()` from the package
-- `src/i18n/tags.hjson` — Search keywords per route and locale
+- `src/pages/*.index.js` — Page registry plus per-page `metadata.tags` for menu search
 - `public/` — Static assets (logo, favicon, images)
 
 The rendering engine (components, layouts, router, store, composables) lives inside the `@docsector/docsector-reader` package — you only maintain your content and configuration.
@@ -74,5 +74,5 @@ The rendering engine (components, layouts, router, store, composables) lives ins
 - Configure your project branding in **docsector.config.js**
 - Define your pages in **src/pages/guide.index.js** (and other `*.index.js` registries)
 - Write your documentation in **Markdown**
-- Add search keywords in **src/i18n/tags.hjson**
+- Add search keywords via **metadata.tags** in each page entry of **src/pages/*.index.js**
 - Customize themes and appearance

package/src/pages/guide/getting-started.overview.pt-BR.md

@@ -64,7 +64,7 @@ Após o `init`, seu projeto terá esta estrutura:
 - `src/pages/guide/` — Páginas tipo guia (arquivos Markdown)
 - `src/pages/manual/` — Páginas tipo manual (arquivos Markdown)
 - `src/i18n/index.js` — Loader i18n usando `buildMessages()` do pacote
-- `src/i18n/tags.hjson` — Palavras-chave de busca por rota e idioma
+- `src/pages/*.index.js` — Registro de páginas com `metadata.tags` por página para busca no menu
 - `public/` — Assets estáticos (logo, favicon, imagens)
 
 O motor de renderização (componentes, layouts, router, store, composables) fica dentro do pacote `@docsector/docsector-reader` — você só mantém seu conteúdo e configuração.
@@ -74,5 +74,5 @@ O motor de renderização (componentes, layouts, router, store, composables) fic
 - Configure o branding do seu projeto em **docsector.config.js**
 - Defina suas páginas em **src/pages/guide.index.js** (e outros registros `*.index.js`)
 - Escreva sua documentação em **Markdown**
-- Adicione palavras-chave de busca em **src/i18n/tags.hjson**
+- Adicione palavras-chave de busca via **metadata.tags** em cada entrada de página em **src/pages/*.index.js**
 - Personalize temas e aparência

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

@@ -81,13 +81,34 @@ Regular blockquotes (without `[!TYPE]`) continue to work as normal.
 
 ### Custom Attributes
 
-The `markdown-it-attrs` plugin enables custom attributes using `:attr;` syntax:
+The `markdown-it-attrs` plugin enables custom attributes using `:attr;` syntax. Code fences support `filename`, `group`, `tab`, and `breadcrumb`:
 
+````markdown
+```php :group="example"; :tab="example.php"; :breadcrumb="src > example.php";
+echo "Example";
 ```
-:filename="example.php";
+```bash :group="example"; :tab="example.sh"; :breadcrumb="scripts > example.sh";
+echo "Example"
 ```
+````
 
-This is used by `DPageSourceCode` to display filenames above code blocks.
+`filename` is shown in the info bar for single blocks. Consecutive fences with the same `group` are rendered as tabs. `tab` sets the tab label, so filename-like labels such as `example.php` receive file icons in the tab. `breadcrumb` sets the breadcrumb segments above the active code block, and the final filename-like segment receives the same file icon.
+
+### Expandable Content
+
+Use `<d-expandable>` to hide secondary content without removing rich Markdown features from the page:
+
+```markdown
+<d-expandable title="More details">
+
+Optional explanations, operational notes, or longer examples.
+
+</d-expandable>
+```
+
+Set `open="true"` when the block should start expanded.
+
+The expandable body supports paragraphs, lists, alerts, code blocks, Mermaid diagrams, tables, raw HTML, and quick links. Keep headings outside the expandable block in this first version, because headings inside the body are flattened to regular paragraphs to preserve the page ToC.
 
 ## Adding a New Language
 

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

@@ -81,13 +81,34 @@ Blockquotes comuns (sem `[!TYPE]`) continuam funcionando normalmente.
 
 ### Atributos Customizados
 
-O plugin `markdown-it-attrs` permite atributos customizados usando sintaxe `:attr;`:
+O plugin `markdown-it-attrs` permite atributos customizados usando sintaxe `:attr;`. Blocos de código cercados suportam `filename`, `group`, `tab` e `breadcrumb`:
 
+````markdown
+```php :group="exemplo"; :tab="exemplo.php"; :breadcrumb="src > exemplo.php";
+echo "Exemplo";
 ```
-:filename="exemplo.php";
+```bash :group="exemplo"; :tab="exemplo.sh"; :breadcrumb="scripts > exemplo.sh";
+echo "Exemplo"
 ```
+````
 
-Isso é usado pelo `DPageSourceCode` para exibir nomes de arquivo acima dos blocos de código.
+`filename` aparece na barra de info em blocos simples. Fences consecutivos com o mesmo `group` são renderizados como abas. `tab` define o rótulo da aba, então labels que parecem arquivo, como `exemplo.php`, recebem ícones na aba. `breadcrumb` define os segmentos acima do bloco ativo, e o segmento final que parece arquivo recebe o mesmo ícone.
+
+### Conteúdo Expansível
+
+Use `<d-expandable>` para esconder conteúdo secundário sem perder os recursos ricos de Markdown da página:
+
+```markdown
+<d-expandable title="Mais detalhes">
+
+Explicações opcionais, notas operacionais ou exemplos maiores.
+
+</d-expandable>
+```
+
+Defina `open="true"` quando o bloco precisar começar aberto.
+
+O corpo do expansível suporta parágrafos, listas, alertas, blocos de código, diagramas Mermaid, tabelas, HTML bruto e quick links. Nesta primeira versão, mantenha títulos fora do bloco expansível, porque títulos dentro do corpo viram parágrafos comuns para preservar o ToC da página.
 
 ## Adicionando um Novo Idioma
 

package/src/pages/guide.index.js

@@ -23,6 +23,12 @@ export default {
     data: {
       'en-US': { title: 'Getting Started' },
       'pt-BR': { title: 'Começando' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'install setup start begin quick project structure',
+        'pt-BR': 'instalar configurar iniciar começar rápido projeto estrutura'
+      }
     }
   },
 
@@ -48,6 +54,12 @@ export default {
     data: {
       'en-US': { title: 'Configuration' },
       'pt-BR': { title: 'Configuração' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'config branding logo name version language links github docsector.config.js',
+        'pt-BR': 'config branding logo nome versão idioma links github docsector.config.js'
+      }
     }
   },
 
@@ -71,6 +83,12 @@ export default {
     data: {
       'en-US': { title: 'Pages & Routing' },
       'pt-BR': { title: 'Páginas & Rotas' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'pages routes routing registry menu navigation path type status subpages',
+        'pt-BR': 'páginas rotas roteamento registro menu navegação caminho tipo status subpages'
+      }
     }
   },
 
@@ -93,6 +111,12 @@ export default {
     data: {
       'en-US': { title: 'i18n & Markdown' },
       'pt-BR': { title: 'i18n & Markdown' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'i18n internationalization language locale hjson markdown content translation',
+        'pt-BR': 'i18n internacionalização idioma locale hjson markdown conteúdo tradução'
+      }
     }
   },
 
@@ -115,6 +139,12 @@ export default {
     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'
+      }
     }
   },
 
@@ -137,6 +167,12 @@ export default {
     data: {
       'en-US': { title: 'Theming' },
       'pt-BR': { title: 'Temas' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'theme dark light mode color css sass variables styling',
+        'pt-BR': 'tema escuro claro modo cor css sass variáveis estilização'
+      }
     }
   },
 
@@ -159,6 +195,12 @@ export default {
     data: {
       'en-US': { title: 'Deployment' },
       'pt-BR': { title: 'Deploy' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'deploy hosting production build static nginx netlify vercel github pages',
+        'pt-BR': 'deploy hospedagem produção build estático nginx netlify vercel github pages'
+      }
     }
   },
 
@@ -181,6 +223,12 @@ export default {
     data: {
       'en-US': { title: 'Plugins' },
       'pt-BR': { title: 'Plugins' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'plugins extensions addons customize',
+        'pt-BR': 'plugins extensões complementos customizar'
+      }
     }
   }
 }

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

@@ -14,7 +14,7 @@
 
 The search input at the top of the menu filters pages by matching the search term against:
 
-1. **Tags** — Defined in `src/i18n/tags.hjson`
+1. **Tags** — Defined per page in `src/pages/*.index.js` under `metadata.tags`
 2. **Page content** — The Markdown source of each page's overview, showcase, and vs subpages
 
 Search is debounced by 300ms and supports the current locale with en-US fallback.

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

@@ -14,7 +14,7 @@
 
 O input de busca no topo do menu filtra páginas comparando o termo de busca com:
 
-1. **Tags** — Definidas em `src/i18n/tags.hjson`
+1. **Tags** — Definidas por página em `src/pages/*.index.js` em `metadata.tags`
 2. **Conteúdo da página** — O source Markdown de cada sub-página overview, showcase e vs
 
 A busca tem debounce de 300ms e suporta o locale atual com fallback para en-US.

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

@@ -0,0 +1,58 @@
+## Overview
+
+`DPageExpandable` renders a collapsible content section backed by the Markdown custom element `<d-expandable>`.
+
+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.
+
+## 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.
+
+## HTML Example
+
+The custom element can be authored directly in page Markdown:
+
+````html
+<d-expandable title="Why hide this content?">
+
+Use expandable blocks when the main section should stay concise but readers may still need more detail.
+
+</d-expandable>
+
+### Open by Default
+
+<d-expandable title="Release checklist" open="true">
+
+- Review breaking changes
+- Update screenshots
+- Run smoke tests
+
+</d-expandable>
+
+### Rich Content
+
+<d-expandable title="Deployment appendix">
+
+> [!TIP]
+> Keep the primary flow in the main section and move optional details here.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>
+````
+
+## Notes
+
+- Use `open="true"` when the section should start expanded.
+- Keep page headings outside the expandable block. Headings inside the body are flattened to regular paragraphs so the page ToC stays stable.
+- Avoid nesting one `<d-expandable>` inside another in this first version.

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

@@ -0,0 +1,58 @@
+## Visão Geral
+
+`DPageExpandable` renderiza uma seção recolhível baseada no elemento customizado de Markdown `<d-expandable>`.
+
+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.
+
+## 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.
+
+## Exemplo em HTML
+
+O custom element pode ser escrito diretamente no Markdown da página:
+
+````html
+<d-expandable title="Por que esconder este conteúdo?">
+
+Use blocos expansíveis quando a seção principal deve continuar concisa, mas o leitor ainda pode precisar de mais detalhes.
+
+</d-expandable>
+
+### Aberto por Padrão
+
+<d-expandable title="Checklist de release" open="true">
+
+- Revisar breaking changes
+- Atualizar screenshots
+- Rodar smoke tests
+
+</d-expandable>
+
+### Conteúdo Rico
+
+<d-expandable title="Apêndice de deploy">
+
+> [!TIP]
+> Mantenha o fluxo principal na seção principal e mova detalhes opcionais para cá.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>
+````
+
+## Observações
+
+- Use `open="true"` quando a seção precisar começar aberta.
+- Mantenha os títulos principais fora do bloco expansível. Títulos dentro do corpo viram parágrafos comuns para manter o ToC estável.
+- Evite aninhar um `<d-expandable>` dentro de outro nesta primeira versão.

package/src/pages/manual/components/d-page-expandable.showcase.en-US.md

@@ -0,0 +1,33 @@
+## Showcase
+
+### Basic
+
+<d-expandable title="Why hide this content?">
+
+Use expandable blocks when the main section should stay concise but readers may still need more detail.
+
+</d-expandable>
+
+### Open by Default
+
+<d-expandable title="Release checklist" open="true">
+
+- Review breaking changes
+- Update screenshots
+- Run smoke tests
+
+</d-expandable>
+
+### Rich Content
+
+<d-expandable title="Deployment appendix">
+
+> [!TIP]
+> Keep the primary flow in the main section and move optional details here.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>

package/src/pages/manual/components/d-page-expandable.showcase.pt-BR.md

@@ -0,0 +1,33 @@
+## Demonstração
+
+### Básico
+
+<d-expandable title="Por que esconder este conteúdo?">
+
+Use blocos expansíveis quando a seção principal deve continuar concisa, mas o leitor ainda pode precisar de mais detalhes.
+
+</d-expandable>
+
+### Aberto por Padrão
+
+<d-expandable title="Checklist de release" open="true">
+
+- Revisar breaking changes
+- Atualizar screenshots
+- Rodar smoke tests
+
+</d-expandable>
+
+### Conteúdo Rico
+
+<d-expandable title="Apêndice de deploy">
+
+> [!TIP]
+> Mantenha o fluxo principal na seção principal e mova detalhes opcionais para cá.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>

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

@@ -42,13 +42,15 @@ Nested content is accumulated into a single HTML string and rendered with `v-htm
 
 ## Custom Attributes
 
-The `markdown-it-attrs` plugin uses `:` and `;` as delimiters. Currently, only the `filename` attribute is used:
+The `markdown-it-attrs` plugin uses `:` and `;` as delimiters. Code fences support `filename`, `group`, `tab`, and `breadcrumb`:
 
+````markdown
+```php :group="server"; :tab="server.php"; :breadcrumb="src > server.php";
+echo "Server ready";
 ```
-:filename="server.php";
-```
+````
 
-This attribute is extracted from fenced code blocks and passed to `DPageSourceCode` for display.
+`filename` is shown in the info bar for single blocks. Consecutive fences with the same `group` become tabs. `tab` sets the tab label, so filename-like labels receive file icons inside the tab. `breadcrumb` sets the breadcrumb segments above the code block, and the final filename-like segment receives the same icon.
 
 ## Anchor IDs
 

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

@@ -42,13 +42,15 @@ Conteúdo aninhado é acumulado em uma única string HTML e renderizado com `v-h
 
 ## Atributos Customizados
 
-O plugin `markdown-it-attrs` usa `:` e `;` como delimitadores. Atualmente, apenas o atributo `filename` é utilizado:
+O plugin `markdown-it-attrs` usa `:` e `;` como delimitadores. Blocos de código cercados suportam `filename`, `group`, `tab` e `breadcrumb`:
 
+````markdown
+```php :group="servidor"; :tab="servidor.php"; :breadcrumb="src > servidor.php";
+echo "Servidor pronto";
 ```
-:filename="servidor.php";
-```
+````
 
-Este atributo é extraído de blocos de código cercados e passado ao `DPageSourceCode` para exibição.
+`filename` aparece na barra de info em blocos simples. Fences consecutivos com o mesmo `group` viram abas. `tab` define o rótulo da aba, então labels que parecem arquivo recebem ícones dentro da aba. `breadcrumb` define os segmentos exibidos acima do bloco de código, e o segmento final que parece arquivo recebe o mesmo ícone.
 
 ## IDs de Âncora
 

package/src/pages/manual/components/d-page-source-code.overview.en-US.md

@@ -1,6 +1,6 @@
 ## Overview
 
-`DPageSourceCode` renders **fenced code blocks** with syntax highlighting, line numbers, copy-to-clipboard functionality, and optional filename display. It uses **Prism.js** for highlighting.
+`DPageSourceCode` renders **fenced code blocks** with syntax highlighting, line numbers, copy-to-clipboard functionality, optional filename display, tabs, and breadcrumbs. It uses **Prism.js** for highlighting.
 
 ## Props
 
@@ -8,8 +8,10 @@
 |------|------|----------|---------|-------------|
 | `index` | `Number` | Yes | — | Unique index for anchor generation |
 | `language` | `String` | No | `'html'` | Programming language for highlighting |
-| `text` | `String` | Yes | — | Raw code text to display |
+| `text` | `String` | No | `''` | Raw code text to display in simple mode |
 | `filename` | `String` | No | `''` | Optional filename shown in the info bar |
+| `breadcrumbs` | `Array` | No | `[]` | Breadcrumb segments shown above the code block |
+| `tabs` | `Array` | No | `[]` | Tab items with label, language, text, and breadcrumbs |
 
 ## Supported Languages
 
@@ -34,7 +36,19 @@ When the code block has more than 1 line, line numbers are displayed on the left
 
 ### Copy to Clipboard
 
-A copy button appears in the info bar. When clicked, it selects the code content and copies it to the clipboard using `document.execCommand('copy')`.
+A copy button appears in the info bar. When clicked, it selects the current code content and copies it to the clipboard using `document.execCommand('copy')`.
+
+### Tabs
+
+Consecutive fenced code blocks with the same `group` attribute are rendered as tabs. Each block can define its visible tab label with `tab`; use that label as the filename when the group should look like editor tabs.
+
+### Breadcrumbs
+
+When a `breadcrumb` attribute is provided, it is rendered above the code block. Use `>` between segments, such as `src > components > DPageSourceCode.vue`.
+
+### File Icons
+
+Tab labels that look like filenames, such as `App.vue`, receive a Material Icon Theme file icon inline before the text. Breadcrumbs add the same file icon only to the final segment when that segment looks like a filename.
 
 ### Filename Display
 

package/src/pages/manual/components/d-page-source-code.overview.pt-BR.md

@@ -1,6 +1,6 @@
 ## Visão Geral
 
-`DPageSourceCode` renderiza **blocos de código cercados** com syntax highlighting, números de linha, funcionalidade de copiar para clipboard e exibição opcional de nome de arquivo. Usa **Prism.js** para highlighting.
+`DPageSourceCode` renderiza **blocos de código cercados** com syntax highlighting, números de linha, funcionalidade de copiar para clipboard, exibição opcional de nome de arquivo, abas e breadcrumbs. Usa **Prism.js** para highlighting.
 
 ## Props
 
@@ -8,8 +8,10 @@
 |------|------|-------------|--------|-----------|
 | `index` | `Number` | Sim | — | Índice único para geração de âncora |
 | `language` | `String` | Não | `'html'` | Linguagem de programação para highlighting |
-| `text` | `String` | Sim | — | Texto de código bruto para exibir |
+| `text` | `String` | Não | `''` | Texto de código bruto para exibir no modo simples |
 | `filename` | `String` | Não | `''` | Nome de arquivo opcional exibido na barra de info |
+| `breadcrumbs` | `Array` | Não | `[]` | Segmentos de breadcrumb exibidos acima do bloco de código |
+| `tabs` | `Array` | Não | `[]` | Itens de aba com label, linguagem, texto e breadcrumbs |
 
 ## Linguagens Suportadas
 
@@ -34,7 +36,19 @@ Quando o bloco de código tem mais de 1 linha, números de linha são exibidos n
 
 ### Copiar para Clipboard
 
-Um botão de cópia aparece na barra de info. Quando clicado, seleciona o conteúdo do código e copia para o clipboard usando `document.execCommand('copy')`.
+Um botão de cópia aparece na barra de info. Quando clicado, seleciona o conteúdo de código atual e copia para o clipboard usando `document.execCommand('copy')`.
+
+### Abas
+
+Blocos de código cercados consecutivos com o mesmo atributo `group` são renderizados como abas. Cada bloco pode definir seu rótulo visível com `tab`; use esse rótulo como nome do arquivo quando o grupo deve parecer abas de editor.
+
+### Breadcrumbs
+
+Quando um atributo `breadcrumb` é fornecido, ele é renderizado acima do bloco de código. Use `>` entre segmentos, como `src > components > DPageSourceCode.vue`.
+
+### Ícones de Arquivo
+
+Labels de abas que parecem nomes de arquivo, como `App.vue`, recebem um ícone do Material Icon Theme inline antes do texto. Breadcrumbs adicionam o mesmo ícone apenas ao segmento final quando esse segmento parece um nome de arquivo.
 
 ### Exibição de Nome de Arquivo
 

package/src/pages/manual/components/d-page-source-code.showcase.en-US.md

@@ -42,9 +42,112 @@ echo "Server running at http://localhost:8181"
 </template>
 ```
 
+### Tabbed Example
+
+```php :group="hello-world"; :tab="HelloWorld.php"; :breadcrumb="src > examples > HelloWorld.php";
+class HelloWorld
+&#123;
+  public function greet(): string
+  &#123;
+    return 'Hello from a tabbed code block';
+  &#125;
+&#125;
+```
+```bash :group="hello-world"; :tab="hello-world.sh"; :breadcrumb="scripts > hello-world.sh";
+#!/bin/bash
+echo "Hello from a tabbed code block"
+```
+
+### Breadcrumb Without Tabs
+
+```javascript :breadcrumb="src > boot > i18n.js";
+import { createI18n } from 'vue-i18n'
+
+export default ({ app }) => {
+  const i18n = createI18n({
+    legacy: false,
+    locale: 'en-US',
+    fallbackLocale: 'en-US'
+  })
+
+  app.use(i18n)
+}
+```
+
+### Long Breadcrumb
+
+```javascript :breadcrumb="workspace-with-a-very-long-name > packages > documentation-renderer-with-a-long-name > src > components > source-code > previews > extremely-deeply-nested-examples > GiantBreadcrumbExample.vue";
+console.log('Long breadcrumb example')
+```
+
+### Long Tabbed Example
+
+```php :group="long-example"; :tab="routes.php"; :breadcrumb="src > routes > routes.php";
+return [
+  '/overview' => 'OverviewPage',
+  '/getting-started' => 'GettingStartedPage',
+  '/configuration' => 'ConfigurationPage',
+  '/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',
+  '/guide' => 'GuideIndex',
+  '/guide/markdown' => 'MarkdownGuide',
+  '/guide/i18n' => 'I18nGuide',
+  '/guide/routing' => 'RoutingGuide',
+  '/guide/search' => 'SearchGuide',
+  '/guide/api' => 'ApiGuide',
+  '/guide/mcp' => 'McpGuide',
+  '/guide/releases' => 'ReleasesGuide',
+  '/guide/changelog' => 'ChangelogGuide',
+];
+```
+```bash :group="long-example"; :tab="deploy.sh"; :breadcrumb="scripts > deploy.sh";
+#!/bin/bash
+set -euo pipefail
+
+steps=(
+  "install dependencies"
+  "check formatting"
+  "run lint"
+  "run unit checks"
+  "build static assets"
+  "generate markdown pages"
+  "generate api catalog"
+  "generate mcp metadata"
+  "write headers"
+  "write routes"
+  "package assets"
+  "publish preview"
+  "verify preview"
+  "promote release"
+  "notify maintainers"
+)
+
+for step in "${steps[@]}"; do
+  echo "Running: ${step}"
+done
+```
+
 ## Features Visible Above
 
 - **Line numbers** on the left side of multi-line blocks
 - **Language label** in the top-right corner
 - **Copy button** next to the language label
+- **Tabs** for consecutive code blocks with the same group
+- **Breadcrumbs** above grouped code examples
+- **Breadcrumbs without tabs** for single code blocks
+- **Condensed long breadcrumbs** that truncate before colliding with the metadata controls
+- **File icons** prepended to filename-like tab labels and final breadcrumb segments
+- **Sticky metadata row** on long grouped code examples
 - **Syntax highlighting** with language-specific coloring