@docsector/docsector-reader 3.3.1 → 3.5.0

package/README.md

@@ -42,6 +42,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
 - 🔽 **Nested Markdown Lists** — Ordered and unordered lists preserve sublist hierarchy across multiple indentation levels
+- ☑️ **Markdown Task Lists** — GitBook-style `- [ ]` and `- [x]` items render as read-only checkboxes with nested subtasks
 - 🖼️ **Block Image Captions & Zoom** — Standalone Markdown images render as zoomable figures, and raw `figure` / `picture` markup supports separate alt text and captions
 - 🧱 **Raw HTML in Markdown** — Renders inline and block HTML tags inside markdown sections (including homepage remote README content)
 - 🧩 **Mermaid Diagrams** — Native support for fenced ` ```mermaid ` blocks, with automatic dark/light theme switching
@@ -72,6 +73,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building
 - 📖 **Expandable Markdown Sections** — Use `<d-expandable title="...">...</d-expandable>` to collapse secondary content while keeping rich Markdown support inside the body
 - 📎 **File Attachment Blocks** — Use `<d-file src="/files/...">...</d-file>` in Markdown to render downloadable file cards with automatic local size detection and support for external URLs
+- 🌐 **Embedded URL Blocks** — Use `<d-embedded-url url="https://...">...</d-embedded-url>` to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
 - 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/<version>/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes
@@ -1035,6 +1037,21 @@ Notes:
 - The block body is rendered as an inline Markdown caption.
 - External URLs also work, so the same syntax can later point to R2 or another CDN without changing the page structure.
 
+### Embedded URL Blocks
+
+```html
+<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
+Optional caption rendered as inline Markdown.
+</d-embedded-url>
+```
+
+Notes:
+
+- Supported providers currently include YouTube, Vimeo, Spotify, and CodePen.
+- The block preserves the original query string, so provider options such as `autoplay=1&loop=1` keep working when supported by the destination service.
+- Unsupported or private URLs fall back to a safe external-link card instead of attempting a generic iframe.
+- Raw HTML remains the escape hatch when you need a provider outside the curated list or full manual iframe control.
+
 ---
 
 

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '3.3.1'
+const VERSION = '3.5.0'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/jsconfig.json

@@ -13,5 +13,5 @@
       "stores/*": ["src/stores/*"]
     }
   },
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "tmp"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",
@@ -74,6 +74,7 @@
     "katex": "^0.17.0",
     "markdown-it": "^13.0.1",
     "markdown-it-attrs": "^4.1.6",
+    "markdown-it-task-lists": "^2.1.1",
     "markdown-it-texmath": "^1.0.0",
     "mermaid": "^11.0.0",
     "prismjs": "^1.27.0",

package/src/components/DPageEmbeddedUrl.vue

@@ -0,0 +1,375 @@
+<script setup>
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import { resolveEmbeddedUrl } from '../composables/useEmbeddedUrl'
+
+defineOptions({
+  name: 'DPageEmbeddedUrl'
+})
+
+const props = defineProps({
+  url: {
+    type: String,
+    default: ''
+  },
+  title: {
+    type: String,
+    default: ''
+  },
+  caption: {
+    type: String,
+    default: ''
+  }
+})
+
+const { t } = useI18n()
+
+const resolved = computed(() => {
+  return resolveEmbeddedUrl(props.url, {
+    title: props.title
+  })
+})
+
+const isEmbedded = computed(() => {
+  return resolved.value.mode === 'embed' && resolved.value.embedSrc !== ''
+})
+
+const isCompactEmbed = computed(() => {
+  return isEmbedded.value && resolved.value.provider === 'spotify'
+})
+
+const displayTitle = computed(() => {
+  return resolved.value.title || props.title || resolved.value.providerLabel || props.url
+})
+
+const displayUrl = computed(() => {
+  return resolved.value.displayUrl || props.url
+})
+
+const compactUrl = computed(() => {
+  return String(displayUrl.value || '').replace(/^https?:\/\//i, '')
+})
+
+const frameStyle = computed(() => {
+  const style = {}
+
+  if (resolved.value.aspectRatio) {
+    style.aspectRatio = resolved.value.aspectRatio
+  } else {
+    style.aspectRatio = 'auto'
+  }
+
+  if (resolved.value.frameHeight > 0) {
+    style.height = `${resolved.value.frameHeight}px`
+    style.minHeight = `${resolved.value.frameHeight}px`
+  }
+
+  return style
+})
+
+const openHref = computed(() => {
+  return resolved.value.canonicalUrl || props.url
+})
+</script>
+
+<template>
+<div
+  class="d-page-embedded-url"
+  :class="{
+    'd-page-embedded-url--compact': isCompactEmbed,
+    'd-page-embedded-url--embedded': isEmbedded,
+    'd-page-embedded-url--fallback': !isEmbedded
+  }"
+>
+  <div
+    v-if="isEmbedded"
+    class="d-page-embedded-url__frame-shell"
+    :style="frameStyle"
+  >
+    <iframe
+      class="d-page-embedded-url__frame"
+      :src="resolved.embedSrc"
+      :title="displayTitle"
+      :allow="resolved.allow || undefined"
+      :allowfullscreen="resolved.allowFullscreen"
+      loading="lazy"
+      referrerpolicy="strict-origin-when-cross-origin"
+    ></iframe>
+  </div>
+
+  <div
+    v-if="!isCompactEmbed || caption"
+    class="d-page-embedded-url__body"
+  >
+    <template v-if="!isCompactEmbed">
+    <div
+      v-if="!isEmbedded"
+      class="d-page-embedded-url__media"
+      aria-hidden="true"
+    >
+      <q-icon
+        :name="resolved.icon || 'link'"
+        size="28px"
+      />
+    </div>
+
+    <div class="d-page-embedded-url__content">
+      <div
+        v-if="resolved.providerLabel"
+        class="d-page-embedded-url__provider"
+      >
+        <q-icon
+          :name="resolved.icon || 'link'"
+          size="16px"
+        />
+        <span>{{ resolved.providerLabel }}</span>
+      </div>
+
+      <div class="d-page-embedded-url__title">{{ displayTitle }}</div>
+
+      <div
+        v-if="compactUrl"
+        class="d-page-embedded-url__url"
+      >{{ compactUrl }}</div>
+
+      <div
+        v-if="caption"
+        class="d-page-embedded-url__caption"
+        v-html="caption"
+      ></div>
+    </div>
+
+    <div class="d-page-embedded-url__actions">
+      <q-btn
+        no-caps
+        unelevated
+        padding="8px 12px"
+        class="d-page-embedded-url__action-button"
+        icon="open_in_new"
+        :label="t('page.file.open')"
+        :href="openHref"
+        target="_blank"
+        rel="noopener noreferrer"
+      />
+    </div>
+    </template>
+
+    <div
+      v-else-if="caption"
+      class="d-page-embedded-url__compact-caption"
+      v-html="caption"
+    ></div>
+  </div>
+</div>
+</template>
+
+<style lang="sass">
+body.body--light
+  --d-page-embedded-url-bg: linear-gradient(180deg, #f7faf5 0%, #ffffff 100%)
+  --d-page-embedded-url-border: rgba(52, 85, 54, 0.14)
+  --d-page-embedded-url-shadow: rgba(52, 85, 54, 0.08)
+  --d-page-embedded-url-frame-bg: rgba(44, 60, 45, 0.04)
+  --d-page-embedded-url-media-bg: rgba(255, 255, 255, 0.92)
+  --d-page-embedded-url-media-border: rgba(52, 85, 54, 0.08)
+  --d-page-embedded-url-accent: #30583a
+  --d-page-embedded-url-meta: #56715c
+  --d-page-embedded-url-caption: #405148
+  --d-page-embedded-url-action-border: rgba(52, 85, 54, 0.18)
+  --d-page-embedded-url-action-hover: rgba(52, 85, 54, 0.06)
+
+body.body--dark
+  --d-page-embedded-url-bg: linear-gradient(180deg, rgba(226, 255, 234, 0.05) 0%, rgba(255, 255, 255, 0.02) 100%)
+  --d-page-embedded-url-border: rgba(214, 245, 224, 0.14)
+  --d-page-embedded-url-shadow: rgba(0, 0, 0, 0.3)
+  --d-page-embedded-url-frame-bg: rgba(255, 255, 255, 0.03)
+  --d-page-embedded-url-media-bg: rgba(255, 255, 255, 0.06)
+  --d-page-embedded-url-media-border: rgba(255, 255, 255, 0.1)
+  --d-page-embedded-url-accent: #b9e2c5
+  --d-page-embedded-url-meta: rgba(255, 255, 255, 0.72)
+  --d-page-embedded-url-caption: rgba(255, 255, 255, 0.9)
+  --d-page-embedded-url-action-border: rgba(214, 245, 224, 0.16)
+  --d-page-embedded-url-action-hover: rgba(214, 245, 224, 0.08)
+
+.d-page-embedded-url
+  margin: 1.5rem 0
+  border: 1px solid var(--d-page-embedded-url-border)
+  border-radius: 18px
+  background: var(--d-page-embedded-url-bg)
+  box-shadow: 0 16px 36px var(--d-page-embedded-url-shadow)
+  overflow: hidden
+
+.d-page-embedded-url__frame-shell
+  position: relative
+  width: 100%
+  min-height: 240px
+  aspect-ratio: 16 / 9
+  background: var(--d-page-embedded-url-frame-bg)
+  border-bottom: 1px solid var(--d-page-embedded-url-border)
+
+.d-page-embedded-url__frame
+  position: absolute
+  inset: 0
+  width: 100%
+  height: 100%
+  border: 0
+  background: transparent
+
+.d-page-embedded-url__body
+  display: flex
+  align-items: center
+  gap: 1rem
+  padding: 0.95rem 1rem
+
+.d-page-embedded-url--embedded
+  .d-page-embedded-url__body
+    padding-top: 1.25rem
+
+  .d-page-embedded-url__content
+    padding-top: 0.1rem
+
+.d-page-embedded-url--compact
+  border: 0
+  border-radius: 0
+  background: transparent
+  box-shadow: none
+  overflow: visible
+
+  .d-page-embedded-url__frame-shell
+    border: 0
+    background: transparent
+
+  .d-page-embedded-url__body
+    display: block
+    padding: 0.6rem 0 0
+
+.d-page-embedded-url__compact-caption
+  margin-top: 0.65rem
+  color: var(--d-page-embedded-url-caption)
+
+  > :first-child
+    margin-top: 0
+
+  > :last-child
+    margin-bottom: 0
+
+.d-page-embedded-url__media
+  width: 56px
+  height: 56px
+  flex: 0 0 56px
+  display: flex
+  align-items: center
+  justify-content: center
+  border-radius: 16px
+  background: var(--d-page-embedded-url-media-bg)
+  box-shadow: inset 0 0 0 1px var(--d-page-embedded-url-media-border)
+  color: var(--d-page-embedded-url-accent)
+
+.d-page-embedded-url__content
+  min-width: 0
+  flex: 1 1 auto
+
+.d-page-embedded-url__provider
+  display: inline-flex
+  align-items: center
+  gap: 0.35rem
+  margin-bottom: 0.35rem
+  color: var(--d-page-embedded-url-meta)
+  font-size: 0.82rem
+  font-weight: 700
+  line-height: 1
+  text-transform: uppercase
+  letter-spacing: 0.06em
+
+.d-page-embedded-url__title
+  font-size: 1rem
+  font-weight: 700
+  line-height: 1.4
+  word-break: break-word
+
+.d-page-embedded-url__url
+  margin-top: 0.2rem
+  color: var(--d-page-embedded-url-meta)
+  font-size: 0.84rem
+  line-height: 1.35
+  word-break: break-all
+
+.d-page-embedded-url__caption
+  margin-top: 0.45rem
+  color: var(--d-page-embedded-url-caption)
+
+  > :first-child
+    margin-top: 0
+
+  > :last-child
+    margin-bottom: 0
+
+.d-page-embedded-url__actions
+  flex: 0 0 auto
+  display: flex
+  align-items: center
+  align-self: stretch
+
+.d-page-embedded-url__action-button
+  min-height: 40px
+  border-radius: 10px
+  border: 1px solid var(--d-page-embedded-url-action-border)
+  background: transparent !important
+  color: var(--d-page-embedded-url-accent) !important
+  transition: transform 0.18s ease, background-color 0.18s ease, border-color 0.18s ease
+
+  .q-btn__content
+    gap: 0.45rem
+    font-size: 0.9rem
+    font-weight: 600
+    line-height: 1
+
+  .q-focus-helper,
+  &:before,
+  &:after
+    display: none
+
+  &:hover
+    transform: translateY(-1px)
+    background: var(--d-page-embedded-url-action-hover) !important
+
+  &:focus-visible
+    outline: 2px solid var(--d-page-embedded-url-accent)
+    outline-offset: 2px
+
+.d-page-embedded-url--fallback
+  .d-page-embedded-url__body
+    padding-block: 1.05rem
+
+@media (max-width: 720px)
+  .d-page-embedded-url__frame-shell
+    min-height: 200px
+
+  .d-page-embedded-url__body
+    flex-wrap: wrap
+    align-items: flex-start
+
+  .d-page-embedded-url__actions
+    width: 100%
+    justify-content: flex-start
+
+  .d-page-embedded-url__action-button
+    width: 100%
+    justify-content: center
+
+@media (max-width: 520px)
+  .d-page-embedded-url__body
+    gap: 0.85rem
+    padding: 0.9rem
+
+  .d-page-embedded-url__media
+    width: 48px
+    height: 48px
+    flex-basis: 48px
+
+  .d-page-embedded-url__provider
+    font-size: 0.76rem
+
+  .d-page-embedded-url__title
+    font-size: 0.95rem
+</style>

package/src/components/DPageTokens.vue

@@ -24,6 +24,7 @@ import DMermaidDiagram from './DMermaidDiagram.vue'
 import DPageBlockquote from './DPageBlockquote.vue'
 import DPageImage from './DPageImage.vue'
 import DPageFile from './DPageFile.vue'
+import DPageEmbeddedUrl from './DPageEmbeddedUrl.vue'
 import DQuickLinks from './DQuickLinks.vue'
 import DPageExpandable from './DPageExpandable.vue'
 </script>
@@ -58,10 +59,12 @@ import DPageExpandable from './DPageExpandable.vue'
 
   <ul
     v-else-if="token.tag === 'ul'"
+    v-bind="token.attrs || {}"
     v-html="token.content"
   ></ul>
   <ol
     v-else-if="token.tag === 'ol'"
+    v-bind="token.attrs || {}"
     v-html="token.content"
   ></ol>
 
@@ -103,6 +106,13 @@ import DPageExpandable from './DPageExpandable.vue'
     :caption="token.caption"
   />
 
+  <d-page-embedded-url
+    v-else-if="token.tag === 'embedded-url'"
+    :url="token.url"
+    :title="token.title"
+    :caption="token.caption"
+  />
+
   <d-page-source-code
     v-else-if="token.tag === 'code'"
     :index="id + token.codeIndex"

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

@@ -2,6 +2,7 @@ import MarkdownIt from 'markdown-it'
 import attrs from 'markdown-it-attrs'
 import GithubSlugger from 'github-slugger'
 import katex from 'katex'
+import taskLists from 'markdown-it-task-lists'
 import texmath from 'markdown-it-texmath'
 
 const ALERT_MESSAGE_TYPES = new Set([
@@ -15,6 +16,7 @@ const ALERT_MESSAGE_TYPES = new Set([
 const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
 const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
 const FILE_MARKER_PREFIX = '@@DOCSECTOR_FILE_'
+const EMBEDDED_URL_MARKER_PREFIX = '@@DOCSECTOR_EMBEDDED_URL_'
 const CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
 const MATH_KATEX_OPTIONS = {
   throwOnError: false,
@@ -114,6 +116,32 @@ const restoreShieldedCodeSegments = (source = '', codeSegmentsMap = new Map()) =
   return restored
 }
 
+const escapeHtmlAttributeValue = (value = '') => {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+}
+
+const getTokenAttributes = (element) => {
+  if (!Array.isArray(element?.attrs) || element.attrs.length === 0) {
+    return null
+  }
+
+  return Object.fromEntries(element.attrs.map(([name, value]) => [name, value ?? '']))
+}
+
+const renderTokenAttributes = (element) => {
+  const attributes = getTokenAttributes(element)
+
+  if (attributes === null) {
+    return ''
+  }
+
+  return Object.entries(attributes)
+    .map(([name, value]) => ` ${name}="${escapeHtmlAttributeValue(value)}"`)
+    .join('')
+}
+
 const extractQuickLinksBlocks = (source = '') => {
   const map = new Map()
   let index = 0
@@ -247,6 +275,41 @@ const extractFileBlocks = (source = '') => {
   }
 }
 
+const extractEmbeddedUrlBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs, rawCaption = '') => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const url = decodeHtmlEntities(attrs.url || attrs.href || attrs.src || '').trim()
+
+    if (!url) {
+      return match
+    }
+
+    const marker = `${EMBEDDED_URL_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      url,
+      title: decodeHtmlEntities(attrs.title || '').trim(),
+      caption: String(rawCaption).trim()
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-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)
+
+  return {
+    source: replaced,
+    embeddedUrlMap: map
+  }
+}
+
 const parseFenceAttributes = (raw = '') => {
   const parsed = {}
   const pattern = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s;]+))/g
@@ -468,6 +531,14 @@ const renderBlockToken = (markdown, element, env) => {
   return markdown.renderer.render([element], markdown.options, env).trim()
 }
 
+const renderInlineToken = (markdown, markdownInline, element, env) => {
+  if (Array.isArray(element.children) && element.children.length > 0) {
+    return markdown.renderer.renderInline(element.children, markdown.options, env)
+  }
+
+  return markdownInline.renderInline(element.content, env)
+}
+
 const createMarkdownBlockParser = () => {
   const markdown = installMathSupport(new MarkdownIt({
     html: true
@@ -478,6 +549,11 @@ const createMarkdownBlockParser = () => {
     rightDelimiter: ';',
     allowedAttributes: ['filename', 'group', 'tab', 'breadcrumb']
   })
+  markdown.use(taskLists, {
+    enabled: false,
+    label: false,
+    labelAfter: false
+  })
 
   return markdown
 }
@@ -527,6 +603,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
 
   const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(sourceWithExpandables)
   const { source: sourceWithFiles, fileMap } = extractFileBlocks(sourceWithQuickLinks)
+  const { source: sourceWithEmbeddedUrls, embeddedUrlMap } = extractEmbeddedUrlBlocks(sourceWithFiles)
 
   fileMap.forEach((data, marker) => {
     fileMap.set(marker, {
@@ -535,10 +612,17 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
     })
   })
 
+  embeddedUrlMap.forEach((data, marker) => {
+    embeddedUrlMap.set(marker, {
+      ...data,
+      caption: restoreShieldedCodeSegments(data.caption, codeSegmentsMap)
+    })
+  })
+
   const markdown = createMarkdownBlockParser()
   const markdownInline = createMarkdownInlineParser()
   const markdownEnv = {}
-  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithFiles, codeSegmentsMap), markdownEnv)
+  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithEmbeddedUrls, codeSegmentsMap), markdownEnv)
   const tokens = []
 
   let level = 0
@@ -662,7 +746,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
     }
 
     if (element.type === 'inline') {
-      element.content = markdownInline.renderInline(element.content, markdownEnv)
+      element.content = renderInlineToken(markdown, markdownInline, element, markdownEnv)
     }
 
     if (level === 0) {
@@ -722,6 +806,21 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (embeddedUrlMap.has(element.content.trim())) {
+            const data = embeddedUrlMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'embedded-url',
+              map: element.map,
+              url: data.url,
+              title: data.title,
+              caption: data.caption !== ''
+                ? markdownInline.renderInline(data.caption, markdownEnv)
+                : ''
+            })
+            break
+          }
+
           if (tag === 'p') {
             const imageToken = parseStandaloneImageToken(element.content)
 
@@ -779,23 +878,29 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
       switch (element.type) {
         case 'bullet_list_open':
           if (level === 1) {
+            const attributes = getTokenAttributes(element)
+
             tokens.push({
               tag: 'ul',
-              content: ''
+              content: '',
+              ...(attributes !== null ? { attrs: attributes } : {})
             })
           } else {
-            parent.content += '<ul>'
+            parent.content += `<ul${renderTokenAttributes(element)}>`
           }
           break
 
         case 'ordered_list_open':
           if (level === 1) {
+            const attributes = getTokenAttributes(element)
+
             tokens.push({
               tag: 'ol',
-              content: ''
+              content: '',
+              ...(attributes !== null ? { attrs: attributes } : {})
             })
           } else {
-            parent.content += '<ol>'
+            parent.content += `<ol${renderTokenAttributes(element)}>`
           }
           break
 
@@ -811,7 +916,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           break
 
         case 'list_item_open':
-          parent.content += '<li>'
+          parent.content += `<li${renderTokenAttributes(element)}>`
           break
 
         case 'thead_open':