@docsector/docsector-reader 3.2.0 → 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
@@ -50,7 +52,6 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🔗 **Anchor Navigation** — Right-side Table of Contents tree with scroll tracking and auto-scroll to active section
 - 🖱️ **Active Menu Item UX** — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection
 - 🔎 **Search** — Menu search across all documentation content and tags
-- 🌐 **WebMCP Browser Tools** — Registers in-page tools for browser agents with `registerTool` and optional `provideContext` fallback
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
 - 📚 **Book Tabs with Per-State Colors** — Define `*.book.js` tabs with icons, order, and `color.active` / `color.inactive`
 - 🔀 **Internal Shortcut Pages** — Route entries can redirect with `config.link.to`, keeping localized titles while inheriting icon/status from the destination page
@@ -67,6 +68,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🧭 **Content Signals** — Injects `Content-Signal` policy in `robots.txt` with deterministic, idempotent build output
 - 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`
 - 🌍 **Remote README as Home** — Optional build-time remote README source for homepage with automatic local fallback
+- 🔗 **GitHub-Compatible Heading Anchors** — Markdown headings use GitHub-style slugs so standard README Table of Contents links work inside Docsector
 - 🧬 **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
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
@@ -356,6 +358,7 @@ You can configure Docsector Reader to use a remote README as homepage content.
 - Fetch happens at build-time.
 - The same README content is used for all configured languages.
 - If fetch fails, it falls back to local `src/pages/Homepage.{lang}.md` by default.
+- Standard GitHub-style heading links and README Table of Contents fragments keep working in the rendered homepage.
 
 ### Configure
 
@@ -856,7 +859,12 @@ my-docs/
 │   │   ├── guide.index.js     # Guide page registry (routes + metadata)
 │   │   ├── boot.js            # Boot page data
 │   │   ├── guide/             # Guide pages (.md files)
-│   │   └── manual/            # Manual pages (.md files)
+│   │   └── manual/
+│   │       ├── basic/         # Core UI docs exposed in the main manual nav
+│   │       ├── content/
+│   │       │   ├── blocks/    # User-facing Markdown block docs
+│   │       │   └── structures/ # User-facing page structure docs
+│   │       └── components/    # Legacy/internal engine-facing manual docs
 │   ├── i18n/
 │   │   ├── index.js           # Uses buildMessages() from engine
 │   │   └── languages/         # HJSON locale files
@@ -870,6 +878,10 @@ my-docs/
     └── icons/                 # PWA icons
 ```
 
+  A common manual pattern is to keep core UI references under `src/pages/manual/basic/` with user-friendly page titles and focused entry pages such as Search, Branding, Version Switcher, Edit on GitHub, Translation Progress, and Previous & Next, end-user content references under `src/pages/manual/content/blocks/`, structural docs under `src/pages/manual/content/structures/`, and legacy/internal engine-specific references under `src/pages/manual/components/`.
+
+  Blocks in `src/pages/manual/content/blocks/` should normally provide both `overview` and `showcase` markdown pages, while structural topics can stay overview-only when a visual demo adds little value.
+
 ---
 
 ## 📚 Defining Books (Tabs)

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.0'
+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.0",
+  "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",
@@ -69,6 +69,7 @@
     "autoprefixer": "^10.4.2",
     "axios": "^1.7.7",
     "core-js": "^3.6.5",
+    "github-slugger": "^2.0.0",
     "hjson": "^3.2.2",
     "katex": "^0.17.0",
     "markdown-it": "^13.0.1",
@@ -88,11 +89,6 @@
   },
   "devDependencies": {
     "@quasar/extras": "^1.16.12",
-    "quasar": "^2.16.6",
-    "vue": "^3.5.13",
-    "vue-i18n": "^9.0.0",
-    "vue-router": "^4.0.0",
-    "vuex": "^4.0.1",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^8.1.0",
     "eslint-plugin-import": "^2.19.1",
@@ -100,7 +96,12 @@
     "eslint-plugin-promise": "^6.0.0",
     "eslint-plugin-vue": "^9.0.0",
     "prettier": "^2.5.1",
-    "vitest": "^2.1.8"
+    "quasar": "^2.16.6",
+    "vitest": "^2.1.8",
+    "vue": "^3.5.13",
+    "vue-i18n": "^9.0.0",
+    "vue-router": "^4.0.0",
+    "vuex": "^4.0.1"
   },
   "browserslist": [
     "last 10 Chrome versions",

package/src/components/DH2.vue

@@ -5,7 +5,7 @@ import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {
-    type: Number,
+    type: [String, Number],
     required: true
   },
   value: {

package/src/components/DH3.vue

@@ -5,7 +5,7 @@ import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {
-    type: Number,
+    type: [String, Number],
     required: true
   },
   value: {

package/src/components/DH4.vue

@@ -5,7 +5,7 @@ import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {
-    type: Number,
+    type: [String, Number],
     required: true
   },
   value: {

package/src/components/DH5.vue

@@ -5,7 +5,7 @@ import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {
-    type: Number,
+    type: [String, Number],
     required: true
   },
   value: {

package/src/components/DH6.vue

@@ -5,7 +5,7 @@ import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {
-    type: Number,
+    type: [String, Number],
     required: true
   },
   value: {

package/src/components/DMenu.vue

@@ -162,7 +162,7 @@ const normalizeRoutePath = (path) => {
 }
 
 const getTopRoutes = () => {
-  return ($router.options.routes || []).slice(0, -2)
+  return ($router.options.routes || []).slice(0, -2).filter(route => route?.meta?.menu?.hidden !== true)
 }
 
 const routeHasSubpage = (route, subpageName) => {

package/src/components/DPage.vue

@@ -150,11 +150,7 @@ const subroute = (to) => {
   }
 
   if (relative === to) {
-    if (to !== '/showcase') {
-      return router.push({ hash: '#0' })
-    } else {
-      return router.push({ hash: '#1' })
-    }
+    return router.push({ hash: '#0' })
   }
 
   router.push(path)
@@ -237,6 +233,30 @@ const handleMainScrollKeys = (event) => {
   container.scrollTop = nextTop
 }
 
+const handleContentAnchorClick = (event) => {
+  if (event.defaultPrevented || event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
+    return
+  }
+
+  const target = event.target
+  if (!(target instanceof Element)) {
+    return
+  }
+
+  const link = target.closest('a[href]')
+  if (!link) {
+    return
+  }
+
+  const href = link.getAttribute('href') || ''
+  if (!href.startsWith('#') || href === '#') {
+    return
+  }
+
+  event.preventDefault()
+  navigate(href)
+}
+
 const handlePageScroll = (scrollState) => {
   scrolling(scrollState)
   syncReadingProgress(scrollState?.position?.top)
@@ -327,7 +347,7 @@ watch(() => route.fullPath, () => {
 
   <q-page id="page">
     <q-scroll-area class="content" :class="main" ref="pageScrollArea">
-      <div id="scroll-container">
+      <div id="scroll-container" @click="handleContentAnchorClick">
         <slot />
       </div>
       <d-page-meta v-if="!disableNav" />

package/src/components/DPageAnchor.vue

@@ -21,19 +21,13 @@ const expanded = computed({
   get() {
     return store.getters['page/nodesExpanded']
   },
-  set(value) {
+  set() {
     // console.log(value)
   }
 })
 const selected = computed({
   get() {
-    let anchor = store.state.page.anchor
-
-    if (store.state.page.relative !== '' && anchor === 0) {
-      anchor = anchor + 1
-    }
-
-    return anchor
+    return store.state.page.anchor
   },
   set(value) {
     navigate(value)
@@ -90,7 +84,7 @@ onMounted(() => {
   const id = route.hash.replace(/^#+/g, '')
   if (id) {
     setTimeout(() => {
-      anchor(id)
+      anchor(route.hash)
     }, 500)
   }
 })

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/DPageMeta.vue

@@ -156,6 +156,7 @@ const getVersionSiblingPath = (offset) => {
   const currentPath = normalizeRoutePath(route.matched?.[0]?.path || `/${store.state.page.base}`)
   const routes = router.options.routes
     .slice(0, -2)
+    .filter(item => item?.meta?.menu?.hidden !== true)
     .filter(item => !versionId || item?.meta?.version === versionId)
 
   const index = routes.findIndex(item => normalizeRoutePath(item.path) === currentPath)

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>
@@ -30,27 +31,27 @@ import DPageExpandable from './DPageExpandable.vue'
 <template v-for="(token, index) in tokens" :key="`${token.tag}-${index}`">
   <d-h2
     v-if="token.tag === 'h2'"
-    :id="id + token.map[0]"
+    :id="token.anchorId"
     :value="token.content"
   />
   <d-h3
     v-else-if="token.tag === 'h3'"
-    :id="id + token.map[0]"
+    :id="token.anchorId"
     :value="token.content"
   />
   <d-h4
     v-else-if="token.tag === 'h4'"
-    :id="id + token.map[0]"
+    :id="token.anchorId"
     :value="token.content"
   />
   <d-h5
     v-else-if="token.tag === 'h5'"
-    :id="id + token.map[0]"
+    :id="token.anchorId"
     :value="token.content"
   />
   <d-h6
     v-else-if="token.tag === 'h6'"
-    :id="id + token.map[0]"
+    :id="token.anchorId"
     :value="token.content"
   />
 
@@ -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