@docsector/docsector-reader 3.6.0 → 4.0.0

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

@@ -15,6 +15,8 @@ const ALERT_MESSAGE_TYPES = new Set([
 
 const CARDS_MARKER_PREFIX = '@@DOCSECTOR_CARDS_'
 const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
+const TIMELINE_MARKER_PREFIX = '@@DOCSECTOR_TIMELINE_'
+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_'
@@ -147,11 +149,11 @@ const extractQuickLinksBlocks = (source = '') => {
   const map = new Map()
   let index = 0
 
-  const blockPattern = /<d-quick-links\b([^>]*)>([\s\S]*?)<\/d-quick-links>/gi
+  const blockPattern = /<d-block-quick-links\b([^>]*)>([\s\S]*?)<\/d-block-quick-links>/gi
   const replaced = String(source).replace(blockPattern, (_, blockAttrsRaw, inner) => {
     const blockAttrs = parseCustomTagAttributes(blockAttrsRaw)
     const items = []
-    const itemPattern = /<d-quick-link\b([^>]*)\/?\s*>/gi
+    const itemPattern = /<d-block-quick-link\b([^>]*)\/?\s*>/gi
 
     let itemMatch = itemPattern.exec(inner)
     while (itemMatch !== null) {
@@ -195,11 +197,11 @@ const extractCardsBlocks = (source = '') => {
   const map = new Map()
   let index = 0
 
-  const blockPattern = /<d-(?:block-)?cards\b([^>]*)>([\s\S]*?)<\/d-(?:block-)?cards>/gi
+  const blockPattern = /<d-block-cards\b([^>]*)>([\s\S]*?)<\/d-block-cards>/gi
   const replaced = String(source).replace(blockPattern, (_, blockAttrsRaw, inner) => {
     const blockAttrs = parseCustomTagAttributes(blockAttrsRaw)
     const items = []
-    const itemPattern = /<d-(?:block-)?card\b([^>]*)\/?\s*>/gi
+    const itemPattern = /<d-block-card\b([^>]*)\/?\s*>/gi
 
     let itemMatch = itemPattern.exec(inner)
     while (itemMatch !== null) {
@@ -244,11 +246,166 @@ const parseExpandableOpenState = (raw = '') => {
   return ['1', 'true', 'yes', 'on'].includes(String(raw).trim().toLowerCase())
 }
 
+const parseTimelineTags = (raw = '') => {
+  return decodeHtmlEntities(raw)
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .map((label) => ({
+      label,
+      color: '',
+      textColor: '',
+      icon: ''
+    }))
+}
+
+const parseTimelineTagLabel = (raw = '') => {
+  return decodeHtmlEntities(String(raw).replace(/<[^>]+>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+const createTimelineTag = (rawAttrs = '', rawLabel = '') => {
+  const attrs = parseCustomTagAttributes(rawAttrs)
+  const label = parseTimelineTagLabel(attrs.label || rawLabel)
+
+  if (label === '') {
+    return null
+  }
+
+  return {
+    label,
+    color: decodeHtmlEntities(attrs.color || '').trim(),
+    textColor: decodeHtmlEntities(attrs['text-color'] || attrs.textColor || '').trim(),
+    icon: decodeHtmlEntities(attrs.icon || '').trim()
+  }
+}
+
+const extractTimelineItemTags = (source = '') => {
+  const tags = []
+
+  const replaceBlock = (match, rawAttrs, rawLabel = '') => {
+    const tag = createTimelineTag(rawAttrs, rawLabel)
+
+    if (tag !== null) {
+      tags.push(tag)
+      return '\n'
+    }
+
+    return match
+  }
+
+  const replaced = String(source).replace(
+    /<d-block-timeline-tag\b([^>]*?)(?:\/\s*>|>([\s\S]*?)<\/d-block-timeline-tag>)/gi,
+    replaceBlock
+  )
+
+  return {
+    content: replaced,
+    tags
+  }
+}
+
+const extractTimelineBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const blockPattern = /<d-block-timeline\b([^>]*)>([\s\S]*?)<\/d-block-timeline>/gi
+  const replaced = String(source).replace(blockPattern, (match, _rawAttrs, inner) => {
+    const items = []
+    const itemPattern = /<d-block-timeline-item\b([^>]*)>([\s\S]*?)<\/d-block-timeline-item>/gi
+
+    let itemMatch = itemPattern.exec(inner)
+    while (itemMatch !== null) {
+      const attrs = parseCustomTagAttributes(itemMatch[1])
+      const date = decodeHtmlEntities(attrs.date || '').trim()
+      const { content: itemContent, tags } = extractTimelineItemTags(itemMatch[2])
+
+      if (date) {
+        items.push({
+          date,
+          tags: [...parseTimelineTags(attrs.tags || ''), ...tags],
+          anchor: decodeHtmlEntities(attrs.anchor || attrs.id || '').trim(),
+          content: itemContent
+        })
+      }
+
+      itemMatch = itemPattern.exec(inner)
+    }
+
+    if (items.length === 0) {
+      return match
+    }
+
+    const marker = `${TIMELINE_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      items
+    })
+
+    return `\n${marker}\n`
+  })
+
+  return {
+    source: replaced,
+    timelineMap: map
+  }
+}
+
+const extractStepperBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const blockPattern = /<d-block-stepper\b([^>]*)>([\s\S]*?)<\/d-block-stepper>/gi
+  const replaced = String(source).replace(blockPattern, (match, _rawAttrs, inner) => {
+    const steps = []
+    const stepPattern = /<d-block-step\b([^>]*)>([\s\S]*?)<\/d-block-step>/gi
+
+    let stepMatch = stepPattern.exec(inner)
+    while (stepMatch !== null) {
+      const attrs = parseCustomTagAttributes(stepMatch[1])
+      const title = attrs.title || ''
+
+      if (title) {
+        steps.push({
+          title,
+          icon: attrs.icon || '',
+          activeIcon: attrs['active-icon'] || '',
+          doneIcon: attrs['done-icon'] || '',
+          errorIcon: attrs['error-icon'] || '',
+          content: stepMatch[2]
+        })
+      }
+
+      stepMatch = stepPattern.exec(inner)
+    }
+
+    if (steps.length === 0) {
+      return match
+    }
+
+    const marker = `${STEPPER_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      steps
+    })
+
+    return `\n${marker}\n`
+  })
+
+  return {
+    source: replaced,
+    stepperMap: map
+  }
+}
+
 const extractExpandableBlocks = (source = '') => {
   const map = new Map()
   let index = 0
 
-  const blockPattern = /<d-expandable\b([^>]*)>([\s\S]*?)<\/d-expandable>/gi
+  const blockPattern = /<d-block-expandable\b([^>]*)>([\s\S]*?)<\/d-block-expandable>/gi
   const replaced = String(source).replace(blockPattern, (_, rawAttrs, inner) => {
     const attrs = parseCustomTagAttributes(rawAttrs)
     const marker = `${EXPANDABLE_MARKER_PREFIX}${index}@@`
@@ -314,10 +471,10 @@ const extractFileBlocks = (source = '') => {
     return `\n${marker}\n`
   }
 
-  const replacedSelfClosing = String(source).replace(/<d-file\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+  const replacedSelfClosing = String(source).replace(/<d-block-file\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
     return replaceBlock(match, rawAttrs)
   })
-  const replaced = replacedSelfClosing.replace(/<d-file\b([^>]*)>([\s\S]*?)<\/d-file>/gi, replaceBlock)
+  const replaced = replacedSelfClosing.replace(/<d-block-file\b([^>]*)>([\s\S]*?)<\/d-block-file>/gi, replaceBlock)
 
   return {
     source: replaced,
@@ -349,10 +506,10 @@ const extractEmbeddedUrlBlocks = (source = '') => {
     return `\n${marker}\n`
   }
 
-  const replacedSelfClosing = String(source).replace(/<d-embedded-url\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+  const replacedSelfClosing = String(source).replace(/<d-block-embedded-url\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
     return replaceBlock(match, rawAttrs)
   })
-  const replaced = replacedSelfClosing.replace(/<d-embedded-url\b([^>]*)>([\s\S]*?)<\/d-embedded-url>/gi, replaceBlock)
+  const replaced = replacedSelfClosing.replace(/<d-block-embedded-url\b([^>]*)>([\s\S]*?)<\/d-block-embedded-url>/gi, replaceBlock)
 
   return {
     source: replaced,
@@ -403,6 +560,12 @@ const escapeHtml = (value = '') => {
     .replace(/'/g, '&#39;')
 }
 
+const stripHtmlTags = (value = '') => {
+  return decodeHtmlEntities(String(value).replace(/<[^>]+>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 const extractTagAttributes = (html = '', tagName = '') => {
   const match = String(html).match(new RegExp(`<${tagName}\\b([^>]*)\\/?>(?![\\s\\S]*<${tagName}\\b)`, 'i'))
 
@@ -635,6 +798,35 @@ const getHeadingAnchorId = (markdown, currentTag, element, env, parserState) =>
   return parserState.headingSlugger.slug(headingText)
 }
 
+const getTimelineItemTitle = (tokens = []) => {
+  for (const token of tokens) {
+    if (typeof token?.content !== 'string') {
+      continue
+    }
+
+    const text = stripHtmlTags(token.content)
+    if (text !== '') {
+      return text
+    }
+  }
+
+  return ''
+}
+
+const getTimelineItemAnchorId = ({ item, itemTokens, itemIndex, parserState }) => {
+  const explicitAnchor = decodeHtmlEntities(item.anchor || '').trim()
+
+  if (explicitAnchor !== '') {
+    return parserState.headingSlugger.slug(explicitAnchor)
+  }
+
+  const title = getTimelineItemTitle(itemTokens)
+  const fallbackTitle = title || `item-${itemIndex + 1}`
+  const seed = [item.date, fallbackTitle].filter(Boolean).join(' ')
+
+  return parserState.headingSlugger.slug(seed)
+}
+
 export const tokenizePageSectionSource = (source = '', options = {}) => {
   const {
     allowHeadingTokens = true,
@@ -642,7 +834,31 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   } = options
   const normalizedSource = normalizePageSectionSource(source)
   const { source: sourceWithShieldedCode, codeSegmentsMap } = shieldMarkdownCodeSegments(normalizedSource)
-  const { source: sourceWithExpandables, expandableMap } = extractExpandableBlocks(sourceWithShieldedCode)
+  const { source: sourceWithTimelines, timelineMap } = extractTimelineBlocks(sourceWithShieldedCode)
+
+  timelineMap.forEach((data, marker) => {
+    timelineMap.set(marker, {
+      ...data,
+      items: data.items.map((item) => ({
+        ...item,
+        content: restoreShieldedCodeSegments(item.content, codeSegmentsMap)
+      }))
+    })
+  })
+
+  const { source: sourceWithSteppers, stepperMap } = extractStepperBlocks(sourceWithTimelines)
+
+  stepperMap.forEach((data, marker) => {
+    stepperMap.set(marker, {
+      ...data,
+      steps: data.steps.map((step) => ({
+        ...step,
+        content: restoreShieldedCodeSegments(step.content, codeSegmentsMap)
+      }))
+    })
+  })
+
+  const { source: sourceWithExpandables, expandableMap } = extractExpandableBlocks(sourceWithSteppers)
 
   expandableMap.forEach((data, marker) => {
     expandableMap.set(marker, {
@@ -815,6 +1031,53 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
         case 'inline': {
           const anchorId = getHeadingAnchorId(markdown, tag, element, markdownEnv, parserState)
 
+          if (timelineMap.has(element.content.trim())) {
+            const data = timelineMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'timeline',
+              items: data.items.map((item, itemIndex) => {
+                const itemTokens = tokenizePageSectionSource(item.content, {
+                  allowHeadingTokens: false,
+                  parserState
+                })
+
+                return {
+                  date: item.date,
+                  tags: item.tags,
+                  anchorId: getTimelineItemAnchorId({
+                    item,
+                    itemTokens,
+                    itemIndex,
+                    parserState
+                  }),
+                  tokens: itemTokens
+                }
+              })
+            })
+            break
+          }
+
+          if (stepperMap.has(element.content.trim())) {
+            const data = stepperMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'stepper',
+              steps: data.steps.map((step) => ({
+                title: step.title,
+                icon: step.icon,
+                activeIcon: step.activeIcon,
+                doneIcon: step.doneIcon,
+                errorIcon: step.errorIcon,
+                tokens: tokenizePageSectionSource(step.content, {
+                  allowHeadingTokens: false,
+                  parserState
+                })
+              }))
+            })
+            break
+          }
+
           if (expandableMap.has(element.content.trim())) {
             const data = expandableMap.get(element.content.trim())
 

package/src/i18n/languages/en-US.hjson

@@ -45,6 +45,11 @@
       download: 'Download',
       open: 'Open'
     },
+    stepper: {
+      continue: 'Continue',
+      back: 'Back',
+      finish: 'Finish'
+    },
     openInChatGPT: 'Open in ChatGPT',
     openInChatGPTCaption: 'Ask ChatGPT about this page',
     openInClaude: 'Open in Claude',

package/src/i18n/languages/pt-BR.hjson

@@ -44,6 +44,11 @@
       download: 'Baixar',
       open: 'Abrir'
     },
+    stepper: {
+      continue: 'Continuar',
+      back: 'Voltar',
+      finish: 'Finalizar'
+    },
     openInChatGPT: 'Abrir no ChatGPT',
     openInChatGPTCaption: 'Pergunte ao ChatGPT sobre esta página',
     openInClaude: 'Abrir no Claude',

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

@@ -118,14 +118,14 @@ echo "Example"
 
 ### Expandable Content
 
-Use `<d-expandable>` to hide secondary content without removing rich Markdown features from the page:
+Use `<d-block-expandable>` to hide secondary content without removing rich Markdown features from the page:
 
 ```markdown
-<d-expandable title="More details">
+<d-block-expandable title="More details">
 
 Optional explanations, operational notes, or longer examples.
 
-</d-expandable>
+</d-block-expandable>
 ```
 
 Set `open="true"` when the block should start expanded.
@@ -134,12 +134,12 @@ The expandable body supports paragraphs, lists, alerts, code blocks, Mermaid dia
 
 ### File Blocks
 
-Use `<d-file>` to publish downloadable attachments from repo-tracked files or external storage without leaving Markdown:
+Use `<d-block-file>` to publish downloadable attachments from repo-tracked files or external storage without leaving Markdown:
 
 ```html
-<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+<d-block-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
 Download the example attachment used in this manual.
-</d-file>
+</d-block-file>
 ```
 
 Store repo-tracked files under `public/files/` and prefer absolute site paths such as `/files/...`.

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

@@ -118,14 +118,14 @@ echo "Exemplo"
 
 ### Conteúdo Expansível
 
-Use `<d-expandable>` para esconder conteúdo secundário sem perder os recursos ricos de Markdown da página:
+Use `<d-block-expandable>` para esconder conteúdo secundário sem perder os recursos ricos de Markdown da página:
 
 ```markdown
-<d-expandable title="Mais detalhes">
+<d-block-expandable title="Mais detalhes">
 
 Explicações opcionais, notas operacionais ou exemplos maiores.
 
-</d-expandable>
+</d-block-expandable>
 ```
 
 Defina `open="true"` quando o bloco precisar começar aberto.
@@ -134,12 +134,12 @@ O corpo do expansível suporta parágrafos, listas, alertas, blocos de código,
 
 ### Blocos de Arquivo
 
-Use `<d-file>` para publicar anexos baixáveis a partir de arquivos versionados no repositório ou de storage externo sem sair do Markdown:
+Use `<d-block-file>` para publicar anexos baixáveis a partir de arquivos versionados no repositório ou de storage externo sem sair do Markdown:
 
 ```html
-<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+<d-block-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
 Baixe o anexo de exemplo usado neste manual.
-</d-file>
+</d-block-file>
 ```
 
 Guarde arquivos versionados no repositório em `public/files/` e prefira caminhos absolutos do site, como `/files/...`.

package/src/pages/guide/theming.overview.en-US.md

@@ -48,7 +48,7 @@ Components use CSS custom properties for theme-aware styling:
 
 ## Customizing Code Block Colors
 
-The `DPageSourceCode` component has separate color schemes for light and dark modes, using Prism.js token classes. Override `token.*` classes in the `.source-code` SASS block to customize syntax highlighting colors.
+The `DBlockSourceCode` component has separate color schemes for light and dark modes, using Prism.js token classes. Override `token.*` classes in the `.source-code` SASS block to customize syntax highlighting colors.
 
 ## Font Families
 

package/src/pages/guide/theming.overview.pt-BR.md

@@ -48,7 +48,7 @@ Os componentes usam propriedades CSS customizadas para estilização consciente
 
 ## Customizando Cores dos Blocos de Código
 
-O componente `DPageSourceCode` tem esquemas de cores separados para modos claro e escuro, usando classes de token do Prism.js. Sobrescreva as classes `token.*` no bloco SASS `.source-code` para customizar as cores de syntax highlighting.
+O componente `DBlockSourceCode` tem esquemas de cores separados para modos claro e escuro, usando classes de token do Prism.js. Sobrescreva as classes `token.*` no bloco SASS `.source-code` para customizar as cores de syntax highlighting.
 
 ## Famílias de Fontes
 

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

@@ -7,15 +7,15 @@ This block is a higher-level alternative to raw iframe markup when the source is
 ## Markdown Syntax
 
 ```html
-<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
+<d-block-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
 Optional caption rendered as inline Markdown.
-</d-embedded-url>
+</d-block-embedded-url>
 ```
 
 You can also omit the caption body when the provider preview already gives enough context:
 
 ```html
-<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P" />
+<d-block-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P" />
 ```
 
 ## Supported Providers

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

@@ -7,15 +7,15 @@ Este block é uma alternativa de nível mais alto ao uso manual de iframe quando
 ## Sintaxe Markdown
 
 ```html
-<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="Demo do player do YouTube">
+<d-block-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="Demo do player do YouTube">
 Legenda opcional renderizada como Markdown inline.
-</d-embedded-url>
+</d-block-embedded-url>
 ```
 
 Você também pode omitir o corpo quando o preview do provider já entrega contexto suficiente:
 
 ```html
-<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P" />
+<d-block-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P" />
 ```
 
 ## Providers suportados

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

@@ -2,24 +2,24 @@
 
 ### YouTube Video
 
-<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE&autoplay=1&loop=1" title="YouTube player demo">
+<d-block-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE&autoplay=1&loop=1" title="YouTube player demo">
 The original playback query parameters stay attached to the provider URL.
-</d-embedded-url>
+</d-block-embedded-url>
 
 ### Spotify Track
 
-<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P?si=1234">
+<d-block-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P?si=1234">
 Spotify links render with the provider-specific compact player height.
-</d-embedded-url>
+</d-block-embedded-url>
 
 ### CodePen Demo
 
-<d-embedded-url url="https://codepen.io/team/codepen/pen/PNaGbb?default-tab=result" title="Interactive demo">
+<d-block-embedded-url url="https://codepen.io/team/codepen/pen/PNaGbb?default-tab=result" title="Interactive demo">
 Use the same block for live front-end demos without dropping to raw HTML.
-</d-embedded-url>
+</d-block-embedded-url>
 
 ### Unsupported URL Fallback
 
-<d-embedded-url url="https://example.com/docs/embed-me" title="External API docs">
+<d-block-embedded-url url="https://example.com/docs/embed-me" title="External API docs">
 Unsupported providers render a safe link card so the reading flow still keeps the URL visible and actionable.
-</d-embedded-url>
+</d-block-embedded-url>

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

@@ -2,24 +2,24 @@
 
 ### Vídeo do YouTube
 
-<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE&autoplay=1&loop=1" title="Demo do player do YouTube">
+<d-block-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE&autoplay=1&loop=1" title="Demo do player do YouTube">
 Os parâmetros originais de reprodução continuam anexados à URL do provider.
-</d-embedded-url>
+</d-block-embedded-url>
 
 ### Faixa do Spotify
 
-<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P?si=1234">
+<d-block-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P?si=1234">
 Links do Spotify renderizam com a altura compacta específica do provider.
-</d-embedded-url>
+</d-block-embedded-url>
 
 ### Demo no CodePen
 
-<d-embedded-url url="https://codepen.io/team/codepen/pen/PNaGbb?default-tab=result" title="Demo interativa">
+<d-block-embedded-url url="https://codepen.io/team/codepen/pen/PNaGbb?default-tab=result" title="Demo interativa">
 Use o mesmo block para demos front-end ao vivo sem cair para HTML bruto.
-</d-embedded-url>
+</d-block-embedded-url>
 
 ### Fallback para URL não suportada
 
-<d-embedded-url url="https://example.com/docs/embed-me" title="Documentação externa da API">
+<d-block-embedded-url url="https://example.com/docs/embed-me" title="Documentação externa da API">
 Providers não suportados renderizam um card seguro com link externo, mantendo a URL visível e acionável no fluxo de leitura.
-</d-embedded-url>
+</d-block-embedded-url>

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

@@ -4,32 +4,32 @@ Expandable blocks collapse secondary content behind a clickable title.
 
 They are a good fit when the main section should stay short, but readers may still need optional details, checklists, appendix material, or longer examples.
 
-The block is authored with the custom Markdown element `<d-expandable>`.
+The block is authored with the custom Markdown element `<d-block-expandable>`.
 
 ## HTML Example
 
 The custom element can be authored directly in page Markdown:
 
 ````html
-<d-expandable title="Why hide this content?">
+<d-block-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>
+</d-block-expandable>
 
 ### Open by Default
 
-<d-expandable title="Release checklist" open="true">
+<d-block-expandable title="Release checklist" open="true">
 
 - Review breaking changes
 - Update screenshots
 - Run smoke tests
 
-</d-expandable>
+</d-block-expandable>
 
 ### Rich Content
 
-<d-expandable title="Deployment appendix">
+<d-block-expandable title="Deployment appendix">
 
 > [!TIP]
 > Keep the primary flow in the main section and move optional details here.
@@ -39,11 +39,11 @@ npm install
 npm run build
 ```
 
-</d-expandable>
+</d-block-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.
+- Avoid nesting one `<d-block-expandable>` inside another in this first version.