@docsector/docsector-reader 4.0.1 → 4.2.0

package/src/components/page-section-tokens.js

@@ -20,6 +20,8 @@ const STEPPER_MARKER_PREFIX = '@@DOCSECTOR_STEPPER_'
 const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
 const FILE_MARKER_PREFIX = '@@DOCSECTOR_FILE_'
 const EMBEDDED_URL_MARKER_PREFIX = '@@DOCSECTOR_EMBEDDED_URL_'
+const CODE_EXAMPLE_MARKER_PREFIX = '@@DOCSECTOR_CODE_EXAMPLE_'
+const API_BLOCK_MARKER_PREFIX = '@@DOCSECTOR_API_BLOCK_'
 const CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
 const MATH_KATEX_OPTIONS = {
   throwOnError: false,
@@ -246,6 +248,24 @@ const parseExpandableOpenState = (raw = '') => {
   return ['1', 'true', 'yes', 'on'].includes(String(raw).trim().toLowerCase())
 }
 
+const parseBooleanAttribute = (raw, fallback = false) => {
+  if (raw === undefined || raw === null || raw === '') {
+    return fallback
+  }
+
+  const normalized = String(raw).trim().toLowerCase()
+
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true
+  }
+
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false
+  }
+
+  return fallback
+}
+
 const parseTimelineTags = (raw = '') => {
   return decodeHtmlEntities(raw)
     .split(',')
@@ -517,6 +537,83 @@ const extractEmbeddedUrlBlocks = (source = '') => {
   }
 }
 
+const extractCodeExampleBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs, rawCaption = '') => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const src = decodeHtmlEntities(attrs.src || attrs.file || '').trim()
+
+    if (!src) {
+      return match
+    }
+
+    const marker = `${CODE_EXAMPLE_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      src,
+      title: decodeHtmlEntities(attrs.title || '').trim(),
+      expanded: parseBooleanAttribute(attrs.expanded, false),
+      codepen: parseBooleanAttribute(attrs.codepen, true),
+      scrollable: parseBooleanAttribute(attrs.scrollable, false),
+      overflow: parseBooleanAttribute(attrs.overflow, false),
+      height: decodeHtmlEntities(attrs.height || '').trim(),
+      caption: String(rawCaption).trim()
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-block-code-example\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+  const replaced = replacedSelfClosing.replace(/<d-block-code-example\b([^>]*)>([\s\S]*?)<\/d-block-code-example>/gi, replaceBlock)
+
+  return {
+    source: replaced,
+    codeExampleMap: map
+  }
+}
+
+const extractApiBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs) => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const src = decodeHtmlEntities(attrs.src || '').trim()
+
+    if (!src) {
+      return match
+    }
+
+    const marker = `${API_BLOCK_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      src,
+      title: decodeHtmlEntities(attrs.title || '').trim(),
+      pageLink: parseBooleanAttribute(attrs['page-link'], false)
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-block-api\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+  const replaced = replacedSelfClosing.replace(/<d-block-api\b([^>]*)>([\s\S]*?)<\/d-block-api>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+
+  return {
+    source: replaced,
+    apiBlockMap: map
+  }
+}
+
 const parseFenceAttributes = (raw = '') => {
   const parsed = {}
   const pattern = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s;]+))/g
@@ -871,6 +968,8 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(sourceWithCards)
   const { source: sourceWithFiles, fileMap } = extractFileBlocks(sourceWithQuickLinks)
   const { source: sourceWithEmbeddedUrls, embeddedUrlMap } = extractEmbeddedUrlBlocks(sourceWithFiles)
+  const { source: sourceWithCodeExamples, codeExampleMap } = extractCodeExampleBlocks(sourceWithEmbeddedUrls)
+  const { source: sourceWithApiBlocks, apiBlockMap } = extractApiBlocks(sourceWithCodeExamples)
 
   fileMap.forEach((data, marker) => {
     fileMap.set(marker, {
@@ -886,10 +985,17 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
     })
   })
 
+  codeExampleMap.forEach((data, marker) => {
+    codeExampleMap.set(marker, {
+      ...data,
+      caption: restoreShieldedCodeSegments(data.caption, codeSegmentsMap)
+    })
+  })
+
   const markdown = createMarkdownBlockParser()
   const markdownInline = createMarkdownInlineParser()
   const markdownEnv = {}
-  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithEmbeddedUrls, codeSegmentsMap), markdownEnv)
+  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithApiBlocks, codeSegmentsMap), markdownEnv)
   const tokens = []
 
   let level = 0
@@ -1146,6 +1252,40 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (codeExampleMap.has(element.content.trim())) {
+            const data = codeExampleMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'code-example',
+              map: element.map,
+              codeIndex: parserState.codeIndex++,
+              src: data.src,
+              title: data.title,
+              expanded: data.expanded,
+              codepen: data.codepen,
+              scrollable: data.scrollable,
+              overflow: data.overflow,
+              height: data.height,
+              caption: data.caption !== ''
+                ? markdownInline.renderInline(data.caption, markdownEnv)
+                : ''
+            })
+            break
+          }
+
+          if (apiBlockMap.has(element.content.trim())) {
+            const data = apiBlockMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'api',
+              map: element.map,
+              src: data.src,
+              title: data.title,
+              pageLink: data.pageLink
+            })
+            break
+          }
+
           if (tag === 'p') {
             const imageToken = parseStandaloneImageToken(element.content)
 

package/src/components/source-code-lines.js

@@ -0,0 +1,17 @@
+const normalizeLineBreaks = (text = '') => String(text || '').replace(/\r\n/g, '\n')
+
+export const countRenderedCodeLines = (text = '') => {
+  const normalized = normalizeLineBreaks(text)
+
+  if (normalized === '') {
+    return 0
+  }
+
+  const withoutTerminalBreak = normalized.replace(/\n$/, '')
+
+  if (withoutTerminalBreak === '') {
+    return 1
+  }
+
+  return withoutTerminalBreak.split('\n').length
+}

package/src/examples/manual/code-examples/BasicCounter.vue

@@ -0,0 +1,63 @@
+<template>
+  <div class="basic-counter-example q-pa-md">
+    <q-card class="basic-counter-example__card" flat bordered>
+      <q-card-section>
+        <div class="text-subtitle2 text-grey-7">Interactive preview</div>
+        <div class="basic-counter-example__value">{{ count }}</div>
+        <div class="text-body2 text-grey-7">{{ countLabel }}</div>
+      </q-card-section>
+
+      <q-separator></q-separator>
+
+      <q-card-actions align="right">
+        <q-btn flat color="primary" label="Reset" @click="reset"></q-btn>
+        <q-btn unelevated color="primary" label="Increment" @click="increment"></q-btn>
+      </q-card-actions>
+    </q-card>
+  </div>
+</template>
+
+<script>
+import { computed, ref } from 'vue'
+
+export default {
+  setup () {
+    const count = ref(0)
+    const countLabel = computed(() => count.value === 1 ? 'click recorded' : 'clicks recorded')
+
+    function increment () {
+      count.value++
+    }
+
+    function reset () {
+      count.value = 0
+    }
+
+    return {
+      count,
+      countLabel,
+      increment,
+      reset
+    }
+  }
+}
+</script>
+
+<style scoped>
+.basic-counter-example {
+  display: flex;
+  justify-content: center;
+}
+
+.basic-counter-example__card {
+  max-width: 360px;
+  width: 100%;
+}
+
+.basic-counter-example__value {
+  font-size: 48px;
+  font-weight: 700;
+  line-height: 1;
+  margin: 12px 0 6px;
+}
+</style>

package/src/examples/manual/code-examples/InlineNotice.vue

@@ -0,0 +1,60 @@
+<template>
+  <div class="inline-notice-example q-pa-md">
+    <q-banner rounded class="inline-notice-example__banner">
+      <template #avatar>
+        <q-icon name="tips_and_updates" color="primary"></q-icon>
+      </template>
+
+      <div class="text-weight-medium">{{ title }}</div>
+      <div class="text-body2">{{ message }}</div>
+
+      <template #action>
+        <q-btn flat color="primary" label="Dismiss" @click="dismiss"></q-btn>
+      </template>
+    </q-banner>
+
+    <div v-if="dismissed" class="inline-notice-example__status text-caption">
+      The notice was dismissed.
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+
+export default {
+  setup () {
+    const title = 'Documentation tip'
+    const message = 'Use expanded examples when the source code is part of the lesson.'
+    const dismissed = ref(false)
+
+    function dismiss () {
+      dismissed.value = true
+    }
+
+    return {
+      dismissed,
+      dismiss,
+      message,
+      title
+    }
+  }
+}
+</script>
+
+<style scoped>
+.inline-notice-example {
+  display: grid;
+  gap: 10px;
+}
+
+.inline-notice-example__banner {
+  background: rgba(25, 118, 210, 0.08);
+  border: 1px solid rgba(25, 118, 210, 0.18);
+}
+
+.inline-notice-example__status {
+  color: #607d68;
+  padding-left: 8px;
+}
+</style>

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

@@ -0,0 +1,40 @@
+## Overview
+
+API Reference blocks render a JSON document that follows the existing Quasar API schema directly inside Markdown.
+
+This keeps the viewer compatible with Quasar-style API files while still allowing non-Vue APIs to reuse the same section model for props, methods, events, values, arguments, and config shapes.
+
+The block is authored with the custom Markdown element `<d-block-api>`.
+
+## Markdown Syntax
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `src` | Same-origin JSON path to fetch in the browser |
+| `title` | Optional header override shown above the API card |
+| `page-link` | Shows the Docs button when the JSON has `meta.docsUrl` |
+
+## JSON Source Model
+
+- The first implementation follows the same delivery model as Quasar Docs: the JSON file is served as a public asset and fetched on demand.
+- No Docsector-specific schema is required. If your file already follows the Quasar API structure, it can be rendered as-is.
+- Non-Vue APIs can still use the same shape by filling the sections they need, such as `props`, `methods`, `events`, `value`, `arg`, or `quasarConfOptions`.
+
+## Notes
+
+- `props` are grouped into subtabs when more than one `category` is present.
+- Entries marked with `internal: true` are hidden from the rendered block.
+- The current version expects same-origin JSON assets so the browser can fetch them without CORS workarounds.
+- If the JSON exposes `meta.docsUrl`, `page-link="true"` can surface a Docs button without changing the schema.

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

@@ -0,0 +1,40 @@
+## Visão geral
+
+Os blocos de Referência de API renderizam um documento JSON que segue o schema de API já existente do Quasar diretamente dentro do Markdown.
+
+Isso mantém o viewer compatível com arquivos de API no estilo do Quasar e ainda permite que APIs não-Vue reutilizem o mesmo modelo de seções para props, methods, events, values, arguments e estruturas de configuração.
+
+O bloco é escrito com o elemento Markdown customizado `<d-block-api>`.
+
+## Sintaxe Markdown
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Atributos
+
+| Atributo | Finalidade |
+|----------|------------|
+| `src` | Caminho same-origin do JSON a ser buscado no navegador |
+| `title` | Sobrescreve opcionalmente o título exibido acima do card |
+| `page-link` | Exibe o botão Docs quando o JSON possui `meta.docsUrl` |
+
+## Modelo da Fonte JSON
+
+- A primeira implementação segue o mesmo modelo de entrega do Quasar Docs: o arquivo JSON é servido como asset público e carregado sob demanda.
+- Nenhum schema específico do Docsector é exigido. Se o arquivo já seguir a estrutura de API do Quasar, ele pode ser renderizado sem alterações.
+- APIs não-Vue ainda podem usar a mesma forma preenchendo apenas as seções necessárias, como `props`, `methods`, `events`, `value`, `arg` ou `quasarConfOptions`.
+
+## Notas
+
+- `props` são agrupadas em subtabs quando mais de uma `category` está presente.
+- Entradas marcadas com `internal: true` são ocultadas do bloco renderizado.
+- A versão atual espera assets JSON same-origin para que o navegador faça o fetch sem workarounds de CORS.
+- Se o JSON expuser `meta.docsUrl`, `page-link="true"` pode exibir um botão Docs sem alterar o schema.

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

@@ -0,0 +1,33 @@
+## Showcase
+
+### Quasar JSON Without Refactoring
+
+This example renders a real Quasar API JSON file copied into `public/quasar-api/`.
+
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+### Generic SDK JSON With the Same Schema
+
+This example uses the same section model for a non-Vue HTTP client and also enables the optional Docs button.
+
+<d-block-api src="/api/manual/http-client.json" title="HTTP Client API" page-link="true" />
+
+## Authoring Syntax
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Features Visible Above
+
+- **Quasar JSON compatibility** with a real file served from `public/quasar-api/`
+- **Generic API support** without introducing a new schema
+- **Local filter** across names and descriptions inside the loaded API sections
+- **Grouped props subtabs** when multiple categories exist in the JSON
+- **Optional Docs link** when `meta.docsUrl` is present and `page-link="true"` is used

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

@@ -0,0 +1,33 @@
+## Showcase
+
+### JSON do Quasar Sem Refatoração
+
+Este exemplo renderiza um arquivo JSON de API real do Quasar copiado para `public/quasar-api/`.
+
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+### JSON de SDK Genérico Com o Mesmo Schema
+
+Este exemplo usa o mesmo modelo de seções para um cliente HTTP não-Vue e também ativa o botão opcional de Docs.
+
+<d-block-api src="/api/manual/http-client.json" title="HTTP Client API" page-link="true" />
+
+## Sintaxe de Autoria
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Recursos Visíveis Acima
+
+- **Compatibilidade com JSON do Quasar** usando um arquivo real servido de `public/quasar-api/`
+- **Suporte a APIs genéricas** sem introduzir um novo schema
+- **Filtro local** por nomes e descrições dentro das seções carregadas
+- **Subtabs agrupadas em props** quando múltiplas categorias existem no JSON
+- **Link opcional para Docs** quando `meta.docsUrl` está presente e `page-link="true"` é usado

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

@@ -0,0 +1,56 @@
+## Overview
+
+Code example blocks render project Vue SFCs as live previews inside Markdown pages.
+
+They are useful when documentation needs to show the real behavior of a component and still let readers inspect the exact source behind the preview.
+
+The block is authored with the custom Markdown element `<d-block-code-example>`.
+
+## Example Files
+
+Place example components under `src/examples/**/*.vue` in the project using Docsector.
+
+Docsector discovers those files at build time through Vite. The `src` value is normalized to kebab-case, so this block:
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter" />
+```
+
+resolves this file:
+
+```text
+src/examples/manual/code-examples/BasicCounter.vue
+```
+
+You can also use `file` instead of `src` when migrating examples from Quasar Docs patterns.
+
+## Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `src` | Example id under `src/examples/**/*.vue` |
+| `file` | Alias for `src` |
+| `title` | Header title shown above the preview |
+| `expanded` | Opens the source panel by default when set to `true` |
+| `codepen` | Shows the CodePen action unless set to `false` |
+| `scrollable` | Gives the preview a fixed scrollable height |
+| `overflow` | Allows both horizontal and vertical overflow in the preview |
+| `height` | Sets a custom preview height, such as `360` or `420px` |
+
+## Source Panel
+
+The source button opens the Vue SFC split into Template, Script, Style, and All tabs when those sections are present.
+
+The source panel reuses the standard Docsector code block renderer, so readers get syntax highlighting, copy support, and the same dark/light treatment as regular code blocks.
+
+## GitHub Source Link
+
+The GitHub button opens the example SFC in the project repository when Docsector can derive a repository URL from `github.editBaseUrl` or `links.github` in `docsector.config.js`.
+
+## CodePen Export
+
+The CodePen button is available when the source can be transformed safely for a browser-only demo.
+
+The first implementation supports plain Vue SFCs with a template, optional style, and an Options API `export default` script. Named imports from `vue` and `quasar` are converted to browser globals. Examples that use `<script setup>`, TypeScript scripts, or local imports still render in Docsector, but the CodePen action is disabled.
+
+Set `codepen="false"` when an example is intentionally not meant to be exported.

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

@@ -0,0 +1,56 @@
+## Visão geral
+
+Blocos de exemplos de código renderizam SFCs Vue do projeto como previews ao vivo dentro das páginas Markdown.
+
+Eles são úteis quando a documentação precisa mostrar o comportamento real de um componente e ainda permitir que leitores inspecionem o código fonte exato por trás do preview.
+
+O bloco é escrito com o elemento Markdown customizado `<d-block-code-example>`.
+
+## Arquivos de exemplo
+
+Coloque os componentes de exemplo em `src/examples/**/*.vue` no projeto que usa o Docsector.
+
+O Docsector descobre esses arquivos durante o build com Vite. O valor de `src` é normalizado para kebab-case, então este bloco:
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter" />
+```
+
+resolve este arquivo:
+
+```text
+src/examples/manual/code-examples/BasicCounter.vue
+```
+
+Também é possível usar `file` no lugar de `src` ao migrar exemplos inspirados nos padrões do Quasar Docs.
+
+## Atributos
+
+| Atributo | Finalidade |
+|----------|------------|
+| `src` | Id do exemplo dentro de `src/examples/**/*.vue` |
+| `file` | Alias de `src` |
+| `title` | Título exibido acima do preview |
+| `expanded` | Abre o painel de fonte por padrão quando definido como `true` |
+| `codepen` | Mostra a ação do CodePen, exceto quando definido como `false` |
+| `scrollable` | Dá ao preview uma altura fixa com rolagem |
+| `overflow` | Permite overflow horizontal e vertical no preview |
+| `height` | Define uma altura customizada para o preview, como `360` ou `420px` |
+
+## Painel de fonte
+
+O botão de fonte abre o SFC Vue dividido em abas Template, Script, Style e All quando essas seções existem.
+
+O painel reutiliza o renderizador padrão de blocos de código do Docsector, então leitores recebem syntax highlighting, suporte a cópia e o mesmo tratamento visual em temas claro e escuro.
+
+## Link de fonte no GitHub
+
+O botão do GitHub abre o SFC do exemplo no repositório do projeto quando o Docsector consegue derivar a URL a partir de `github.editBaseUrl` ou `links.github` em `docsector.config.js`.
+
+## Exportação para CodePen
+
+O botão do CodePen fica disponível quando o código pode ser transformado com segurança para uma demo somente no navegador.
+
+A primeira implementação suporta SFCs Vue simples com template, style opcional e script Options API com `export default`. Imports nomeados de `vue` e `quasar` são convertidos para globais do navegador. Exemplos que usam `<script setup>`, scripts TypeScript ou imports locais continuam renderizando no Docsector, mas a ação do CodePen fica desativada.
+
+Use `codepen="false"` quando um exemplo intencionalmente não deve ser exportado.

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

@@ -0,0 +1,38 @@
+## Showcase
+
+### Basic Counter
+
+This example is rendered from a real Vue SFC under `src/examples/manual/code-examples/BasicCounter.vue`.
+
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Use the source button to inspect the SFC sections, or open the compatible demo in CodePen.
+</d-block-code-example>
+
+### Expanded Source by Default
+
+Use `expanded="true"` when the source code is part of the lesson and should be visible as soon as the reader reaches the example.
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+This example intentionally starts with the source panel open.
+</d-block-code-example>
+
+## Authoring Syntax
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Optional caption rendered as inline Markdown.
+</d-block-code-example>
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+The source panel starts open.
+</d-block-code-example>
+```
+
+## Features Visible Above
+
+- **Live preview** rendered from the bundled Vue component
+- **Source toggle** with Template, Script, Style, and All tabs
+- **CodePen action** for compatible examples
+- **GitHub action** pointing to the example SFC
+- **Expanded source state** with `expanded="true"`
+- **Inline Markdown caption** below the preview

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

@@ -0,0 +1,38 @@
+## Showcase
+
+### Contador básico
+
+Este exemplo é renderizado a partir de um SFC Vue real em `src/examples/manual/code-examples/BasicCounter.vue`.
+
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Use o botão de fonte para inspecionar as seções do SFC, ou abra a demo compatível no CodePen.
+</d-block-code-example>
+
+### Fonte expandida por padrão
+
+Use `expanded="true"` quando o código fonte faz parte da explicação e deve aparecer assim que o leitor chegar ao exemplo.
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+Este exemplo intencionalmente começa com o painel de fonte aberto.
+</d-block-code-example>
+
+## Sintaxe de autoria
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Legenda opcional renderizada como Markdown inline.
+</d-block-code-example>
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+O painel de fonte começa aberto.
+</d-block-code-example>
+```
+
+## Recursos visíveis acima
+
+- **Preview ao vivo** renderizado a partir do componente Vue empacotado
+- **Alternância de fonte** com abas Template, Script, Style e All
+- **Ação do CodePen** para exemplos compatíveis
+- **Ação do GitHub** apontando para o SFC do exemplo
+- **Estado de fonte expandida** com `expanded="true"`
+- **Legenda em Markdown inline** abaixo do preview