@docsector/docsector-reader 3.2.1 → 3.2.2

package/README.md

@@ -41,6 +41,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 ## ✨ Features
 
 - 📝 **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
+- 🖼️ **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
 - ➗ **Math & KaTeX** — Native support for inline `$...$` and display `$$...$$` formulas rendered with KaTeX

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.2.1'
+const VERSION = '3.2.2'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/jsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "ignoreDeprecations": "6.0",
     "baseUrl": ".",
     "noUnusedLocals": false,
     "noUnusedParameters": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "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",

package/src/components/DPageImage.vue

@@ -0,0 +1,80 @@
+<script setup>
+import { computed } from 'vue'
+
+defineOptions({
+  name: 'DPageImage'
+})
+
+const props = defineProps({
+  content: {
+    type: String,
+    default: ''
+  },
+  captionHtml: {
+    type: String,
+    default: ''
+  }
+})
+
+const hasCaption = computed(() => {
+  return String(props.captionHtml || '').trim() !== ''
+})
+</script>
+
+<template>
+<figure class="d-page-image">
+  <q-zoom
+    class="d-page-image__zoom"
+    background-color="rgba(18, 18, 20, 0.96)"
+    show-close-button
+  >
+    <div class="d-page-image__media" v-html="content"></div>
+  </q-zoom>
+
+  <figcaption v-if="hasCaption" class="d-page-image__caption" v-html="captionHtml"></figcaption>
+</figure>
+</template>
+
+<style lang="sass" scoped>
+.d-page-image
+  display: flex
+  flex-direction: column
+  align-items: center
+  gap: 0.75rem
+  width: 100%
+  margin: 1.75rem auto
+  text-align: center
+
+.d-page-image__zoom
+  display: inline-block
+  width: fit-content
+  max-width: 100%
+
+.d-page-image__media
+  display: inline-flex
+  align-items: center
+  justify-content: center
+  line-height: 0
+  max-width: 100%
+
+  :deep(img),
+  :deep(picture)
+    display: block
+    max-width: 100%
+
+.d-page-image__caption
+  max-width: min(100%, 42rem)
+  margin: 0
+  padding: 0 1rem
+  color: inherit
+  opacity: 0.72
+  font-size: 0.92rem
+  line-height: 1.45
+  text-align: center
+
+  :deep(p)
+    margin: 0
+
+  :deep(*)
+    color: inherit
+</style>

package/src/components/DPageTokens.vue

@@ -22,6 +22,7 @@ import DH6 from './DH6.vue'
 import DPageSourceCode from './DPageSourceCode.vue'
 import DMermaidDiagram from './DMermaidDiagram.vue'
 import DPageBlockquote from './DPageBlockquote.vue'
+import DPageImage from './DPageImage.vue'
 import DQuickLinks from './DQuickLinks.vue'
 import DPageExpandable from './DPageExpandable.vue'
 </script>
@@ -75,6 +76,12 @@ import DPageExpandable from './DPageExpandable.vue'
     v-html="token.content"
   ></div>
 
+  <d-page-image
+    v-else-if="token.tag === 'image'"
+    :content="token.content"
+    :caption-html="token.captionHtml"
+  />
+
   <p
     v-else-if="token.tag === 'p'"
     v-html="token.content"

package/src/components/QZoom.js

@@ -6,15 +6,13 @@
 
 import {
   h,
+  Teleport,
   ref, computed,
   onMounted, onBeforeUnmount
 } from 'vue'
 
 import { useColorize } from 'q-colorize-mixin'
 
-import { dom } from 'quasar'
-const { offset } = dom
-
 import './QZoom.sass'
 
 // @
@@ -34,7 +32,12 @@ export default {
     initialScaleText: { type: Number, default: 100, validator: v => v >= 50 && v <= 500 },
     noCenter: Boolean,
     noWheelScale: Boolean,
-    noEscClose: Boolean
+    noEscClose: Boolean,
+    showCloseButton: Boolean,
+    closeButtonLabel: {
+      type: String,
+      default: 'Close zoom'
+    }
   },
 
   setup (props, { emit, slots }) {
@@ -183,13 +186,29 @@ export default {
       }
     }
 
+    const onOverlayClick = (e) => {
+      if (isZoomed.value) {
+        hide()
+
+        e.preventDefault()
+      }
+    }
+
+    const stopEvent = (e) => {
+      e.stopPropagation()
+    }
+
     const getPosition = () => {
-      const position = offset(vComponent.value)
+      const rect = vComponent.value.getBoundingClientRect()
+      const position = {
+        left: rect.left,
+        top: rect.top
+      }
 
       position.left = position.left + 'px'
       position.top = position.top + 'px'
-      position.width = vComponent.value.clientWidth + 'px'
-      position.height = vComponent.value.clientHeight + 'px'
+      position.width = rect.width + 'px'
+      position.height = rect.height + 'px'
 
       return position
     }
@@ -245,7 +264,34 @@ export default {
           fontSize: props.scaleText && !props.scale && `${scaleTextValue.value}%`
         }
       }), [
-        slot && slot({ zoomed: isZoomed.value })
+        h('div', {
+          class: 'q-zoom__content-inner',
+          onClick: stopEvent
+        }, [
+          slot && slot({ zoomed: isZoomed.value })
+        ])
+      ])
+    }
+
+    const __renderCloseButton = () => {
+      if (!props.showCloseButton) {
+        return null
+      }
+
+      return h('button', {
+        type: 'button',
+        class: 'q-zoom__close-button',
+        'aria-label': props.closeButtonLabel,
+        title: props.closeButtonLabel,
+        onClick: (e) => {
+          stopEvent(e)
+          hide()
+        }
+      }, [
+        h('span', {
+          class: 'q-zoom__close-icon',
+          'aria-hidden': 'true'
+        }, '×')
       ])
     }
 
@@ -256,13 +302,18 @@ export default {
 
       return h('div', Colorize.setBackgroundColor(bgColor.value, {
         class: 'q-zoom__overlay' +
-          (props.manual ? '' : ' q-zoom__zoom-out')
+          (props.manual ? '' : ' q-zoom__zoom-out'),
+        onClick: onOverlayClick
       }), [
+        __renderCloseButton(),
         __renderOverlayContent()
       ])
     }
 
-    return () => h('div', {
+    return () => {
+      const overlay = __renderOverlay()
+
+      return h('div', {
       class: 'q-zoom' +
         (props.manual ? '' : ' q-zoom__zoom-in'),
 
@@ -270,9 +321,12 @@ export default {
       onWheel: wheelEvent,
 
       ref: vComponent
-    }, [
-      slots.default && slots.default({ zoomed: isZoomed.value }),
-      __renderOverlay()
-    ])
+      }, [
+        slots.default && slots.default({ zoomed: isZoomed.value }),
+        overlay
+          ? h(Teleport, { to: 'body' }, overlay)
+          : null
+      ])
+    }
   }
 }

package/src/components/QZoom.sass

@@ -22,19 +22,54 @@ $box-shadow: 1px 1px 7px 1px rgba(0,0,0,.2) !default
     padding: 0
     margin: 0
     z-index: 6000
+    overflow: hidden
 
   &__content
-    position: relative
-    display: block
+    position: absolute
+    display: flex
+    align-items: center
+    justify-content: center
     transition: all .5s cubic-bezier(.2,0,.2,1)
     text-align: center
-    vertical-align: middle
     width: 100%
     height: 0
     max-width: 100%
     max-height: 100%
     overflow: hidden
 
+    & > *
+      max-width: 100%
+      max-height: 100%
+
+  &__content-inner
+    display: inline-flex
+    align-items: center
+    justify-content: center
+    max-width: 100%
+    max-height: 100%
+
+  &__close-button
+    position: absolute
+    top: 24px
+    right: 24px
+    width: 56px
+    height: 56px
+    display: inline-flex
+    align-items: center
+    justify-content: center
+    border: 0
+    border-radius: 999px
+    background: rgba(255,255,255,.12)
+    color: #fff
+    cursor: pointer
+    z-index: 6001
+    box-shadow: $box-shadow
+    backdrop-filter: blur(8px)
+
+  &__close-icon
+    font-size: 34px
+    line-height: 1
+
   &__no-center
     text-align: unset
     vertical-align: unset

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

@@ -215,6 +215,97 @@ const parseTokenAttributes = (element) => {
   return parsed
 }
 
+const decodeHtmlEntities = (value = '') => {
+  return String(value)
+    .replace(/"/g, '"')
+    .replace(/'|'/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+
+const escapeHtml = (value = '') => {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+const extractTagAttributes = (html = '', tagName = '') => {
+  const match = String(html).match(new RegExp(`<${tagName}\\b([^>]*)\\/?>(?![\\s\\S]*<${tagName}\\b)`, 'i'))
+
+  if (!match) {
+    return {}
+  }
+
+  return parseCustomTagAttributes(match[1])
+}
+
+const createImageTokenData = (mediaHtml = '', options = {}) => {
+  const {
+    captionHtml = '',
+    fallbackCaptionFromAlt = false
+  } = options
+  const attrs = extractTagAttributes(mediaHtml, 'img')
+  const alt = decodeHtmlEntities(attrs.alt || '')
+  const title = decodeHtmlEntities(attrs.title || '')
+
+  return {
+    tag: 'image',
+    content: String(mediaHtml).trim(),
+    alt,
+    title,
+    captionHtml: captionHtml !== ''
+      ? captionHtml
+      : (fallbackCaptionFromAlt ? escapeHtml(alt) : '')
+  }
+}
+
+const parseStandaloneImageToken = (content = '') => {
+  const trimmed = String(content).trim()
+
+  if (!trimmed.match(/^<img\b[^>]*\/?>(?:\s*)$/i)) {
+    return null
+  }
+
+  return createImageTokenData(trimmed, {
+    fallbackCaptionFromAlt: true
+  })
+}
+
+const parseFigureImageToken = (content = '') => {
+  const trimmed = String(content).trim()
+
+  if (!trimmed.match(/^<figure\b[\s\S]*<\/figure>$/i)) {
+    return null
+  }
+
+  const figureBody = trimmed
+    .replace(/^<figure\b[^>]*>/i, '')
+    .replace(/<\/figure>$/i, '')
+    .trim()
+  const figcaptionMatch = figureBody.match(/<figcaption\b[^>]*>([\s\S]*?)<\/figcaption>/i)
+  const mediaBody = figcaptionMatch
+    ? figureBody.replace(figcaptionMatch[0], '').trim()
+    : figureBody
+  const pictureMatch = mediaBody.match(/^<picture\b[\s\S]*?<\/picture>$/i)
+  const imgMatch = pictureMatch
+    ? pictureMatch[0].match(/<img\b[^>]*\/?>/i)
+    : mediaBody.match(/^<img\b[^>]*\/?>$/i)
+
+  if (!imgMatch) {
+    return null
+  }
+
+  const mediaHtml = pictureMatch ? pictureMatch[0] : imgMatch[0]
+
+  return createImageTokenData(mediaHtml, {
+    captionHtml: figcaptionMatch ? figcaptionMatch[1].trim() : ''
+  })
+}
+
 const parseFenceLanguage = (raw = '') => {
   const cleaned = String(raw)
     .replace(/:[^;]*;/g, ' ')
@@ -520,7 +611,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
       }
 
       switch (element.type) {
-        case 'inline':
+        case 'inline': {
           const anchorId = getHeadingAnchorId(markdown, tag, element, markdownEnv, parserState)
 
           if (expandableMap.has(element.content.trim())) {
@@ -549,6 +640,18 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (tag === 'p') {
+            const imageToken = parseStandaloneImageToken(element.content)
+
+            if (imageToken !== null) {
+              tokens.push({
+                ...imageToken,
+                map: element.map
+              })
+              break
+            }
+          }
+
           tokens.push({
             tag,
             map: element.map,
@@ -557,6 +660,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             info: element.info
           })
           break
+        }
 
         case 'fence':
           pushSourceCodeToken(tokens, element, parserState)
@@ -569,36 +673,59 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           })
           break
 
-        case 'html_block':
+        case 'html_block': {
+          const figureImageToken = parseFigureImageToken(element.content)
+
+          if (figureImageToken !== null) {
+            tokens.push({
+              ...figureImageToken,
+              map: element.map
+            })
+            break
+          }
+
           tokens.push({
             tag: 'html',
             content: element.content
           })
           break
+        }
       }
-    } else if (level === 1) {
+    } else if (level > 0) {
       const parent = tokens[tokens.length - 1]
 
       switch (element.type) {
         case 'bullet_list_open':
-          tokens.push({
-            tag: 'ul',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'ul',
+              content: ''
+            })
+          } else {
+            parent.content += '<ul>'
+          }
           break
 
         case 'ordered_list_open':
-          tokens.push({
-            tag: 'ol',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'ol',
+              content: ''
+            })
+          } else {
+            parent.content += '<ol>'
+          }
           break
 
         case 'table_open':
-          tokens.push({
-            tag: 'table',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'table',
+              content: ''
+            })
+          } else {
+            parent.content += '<table>'
+          }
           break
 
         case 'list_item_open':
@@ -636,6 +763,24 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           parent.content += '</li>'
           break
 
+        case 'bullet_list_close':
+          if (level > 1) {
+            parent.content += '</ul>'
+          }
+          break
+
+        case 'ordered_list_close':
+          if (level > 1) {
+            parent.content += '</ol>'
+          }
+          break
+
+        case 'table_close':
+          if (level > 1) {
+            parent.content += '</table>'
+          }
+          break
+
         case 'thead_close':
           parent.content += '</thead>'
           break

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

@@ -2,15 +2,33 @@
 
 Use standard Markdown images to place screenshots, illustrations, diagrams, and product UI directly inside the reading flow.
 
+When an image appears on its own line, Docsector renders it as a block figure with click-to-zoom behavior.
+For plain Markdown images, the label is used as both the visible caption and the alt text, matching GitBook's block image model.
+
 ## Markdown Syntax
 
 ```markdown
 ![Dashboard overview](/images/example-dashboard.png)
 ```
 
+## Separate Alt Text And Caption
+
+Use raw HTML when the accessibility text and the visible caption should be different, or when you need `<picture>` / `<source>` for light and dark mode variants.
+
+```html
+<figure>
+	<picture>
+		<source srcset="/images/logo-dark.png" media="(prefers-color-scheme: dark)">
+		<img src="/images/logo-light.png" alt="Docsector Reader logo">
+	</picture>
+	<figcaption><p>Docsector Reader brand mark</p></figcaption>
+</figure>
+```
+
 ## Good Practices
 
-- Write descriptive alt text so the image still has meaning without the visual.
+- Write labels that still make sense without the visual, because plain Markdown uses the same text for caption and alt.
+- Use `<figure>` with `<figcaption>` when the visible caption should differ from the accessibility text.
 - Prefer absolute site paths such as `/images/...` for assets stored in `public/images/`.
 - Use screenshots to support the text, not replace the explanation.
-- When default Markdown syntax is not enough, raw HTML can be used for custom wrappers or sizing.
+- Click standalone block images to zoom; inline images that stay inside a paragraph remain on the inline path.

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

@@ -1,11 +1,19 @@
 ## Showcase
 
-### Basic Image
+### Markdown Image With Caption
 
 ![Docsector Reader logo](/images/logo.png)
 
+The label above is rendered as the visible caption and remains the image alt text.
+
 ### Image with Title
 
 ![Docsector Reader logo](/images/logo.png "Docsector Reader")
 
-The alt text remains part of the content model, so the page still communicates meaning if the image cannot be seen.
+The title attribute is preserved on the rendered image, while the block still keeps the same visible caption.
+
+### Raw HTML Figure With Separate Alt And Caption
+
+<figure><img src="/images/logo.png" alt="Docsector Reader brand mark"><figcaption><p>Docsector Reader logo used as a standalone brand image.</p></figcaption></figure>
+
+Click any standalone image block on this page to open the zoom view.