@docsector/docsector-reader 3.1.0 → 3.2.1

package/README.md

@@ -43,13 +43,13 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
 - 🧱 **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
 - 🚨 **GitHub-Style Alerts** — Native support for `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`
 - 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
 - 🔗 **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
@@ -66,6 +66,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
@@ -355,6 +356,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
 
@@ -855,7 +857,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
@@ -869,6 +876,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.1.0'
+const VERSION = '3.2.1'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "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,9 +69,12 @@
     "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",
     "markdown-it-attrs": "^4.1.6",
+    "markdown-it-texmath": "^1.0.0",
     "mermaid": "^11.0.0",
     "prismjs": "^1.27.0",
     "q-colorize-mixin": "^2.0.0-alpha.5"
@@ -86,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",
@@ -98,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/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

@@ -30,27 +30,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"
   />
 

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

@@ -1,5 +1,8 @@
 import MarkdownIt from 'markdown-it'
 import attrs from 'markdown-it-attrs'
+import GithubSlugger from 'github-slugger'
+import katex from 'katex'
+import texmath from 'markdown-it-texmath'
 
 const ALERT_MESSAGE_TYPES = new Set([
   'note',
@@ -12,6 +15,10 @@ const ALERT_MESSAGE_TYPES = new Set([
 const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
 const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
 const CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
+const MATH_KATEX_OPTIONS = {
+  throwOnError: false,
+  strict: 'ignore'
+}
 
 const parseAlertMarker = (rawContent = '') => {
   const match = String(rawContent).trim().match(/^\[!\s*([A-Za-z]+)\s*\]\s*(.*)$/s)
@@ -100,7 +107,7 @@ const restoreShieldedCodeSegments = (source = '', codeSegmentsMap = new Map()) =
   let restored = String(source)
 
   codeSegmentsMap.forEach((content, marker) => {
-    restored = restored.replaceAll(marker, content)
+    restored = restored.replaceAll(marker, () => content)
   })
 
   return restored
@@ -299,10 +306,24 @@ const pushSourceCodeToken = (tokens, element, parserState) => {
   })
 }
 
+const installMathSupport = (markdown) => {
+  markdown.use(texmath, {
+    engine: katex,
+    delimiters: 'dollars',
+    katexOptions: MATH_KATEX_OPTIONS
+  })
+
+  return markdown
+}
+
+const renderBlockToken = (markdown, element, env) => {
+  return markdown.renderer.render([element], markdown.options, env).trim()
+}
+
 const createMarkdownBlockParser = () => {
-  const markdown = new MarkdownIt({
+  const markdown = installMathSupport(new MarkdownIt({
     html: true
-  })
+  }))
 
   markdown.use(attrs, {
     leftDelimiter: ':',
@@ -314,9 +335,9 @@ const createMarkdownBlockParser = () => {
 }
 
 const createMarkdownInlineParser = () => {
-  return new MarkdownIt({
+  return installMathSupport(new MarkdownIt({
     html: true
-  })
+  }))
 }
 
 const normalizePageSectionSource = (source = '') => {
@@ -326,10 +347,24 @@ const normalizePageSectionSource = (source = '') => {
     .replace(/&/g, '&')
 }
 
+const createParserState = () => ({
+  codeIndex: 0,
+  headingSlugger: new GithubSlugger()
+})
+
+const getHeadingAnchorId = (markdown, currentTag, element, env, parserState) => {
+  if (!currentTag || !currentTag.match(/^h[2-6]$/)) {
+    return ''
+  }
+
+  const headingText = markdown.renderer.renderInlineAsText(element.children || [], markdown.options, env).trim()
+  return parserState.headingSlugger.slug(headingText)
+}
+
 export const tokenizePageSectionSource = (source = '', options = {}) => {
   const {
     allowHeadingTokens = true,
-    parserState = { codeIndex: 0 }
+    parserState = createParserState()
   } = options
   const normalizedSource = normalizePageSectionSource(source)
   const { source: sourceWithShieldedCode, codeSegmentsMap } = shieldMarkdownCodeSegments(normalizedSource)
@@ -444,6 +479,11 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
         return
       }
 
+      if (element.type === 'math_block') {
+        blockquote.content += renderBlockToken(markdown, element, markdownEnv)
+        return
+      }
+
       if (element.type.endsWith('_open')) {
         appendBlockquoteTag(element, true)
         return
@@ -481,6 +521,8 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
 
       switch (element.type) {
         case 'inline':
+          const anchorId = getHeadingAnchorId(markdown, tag, element, markdownEnv, parserState)
+
           if (expandableMap.has(element.content.trim())) {
             const data = expandableMap.get(element.content.trim())
 
@@ -510,6 +552,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           tokens.push({
             tag,
             map: element.map,
+            anchorId,
             content: element.content,
             info: element.info
           })
@@ -519,6 +562,13 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           pushSourceCodeToken(tokens, element, parserState)
           break
 
+        case 'math_block':
+          tokens.push({
+            tag: 'html',
+            content: renderBlockToken(markdown, element, markdownEnv)
+          })
+          break
+
         case 'html_block':
           tokens.push({
             tag: 'html',
@@ -574,6 +624,9 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
         case 'inline':
           parent.content += element.content
           break
+        case 'math_block':
+          parent.content += renderBlockToken(markdown, element, markdownEnv)
+          break
         case 'html_inline':
         case 'html_block':
           parent.content += element.content

package/src/composables/useNavigator.js

@@ -9,13 +9,34 @@ export default function useNavigator() {
   const route = useRoute()
   const selected = ref(null)
 
+  const normalizeDomAnchorId = (id) => {
+    if (id === null || id === undefined || id === false) {
+      return ''
+    }
+
+    let normalized = String(id).replace(/^#+/g, '')
+
+    try {
+      normalized = decodeURIComponent(normalized)
+    } catch {
+      // Keep the raw fragment when it is not valid percent-encoding.
+    }
+
+    return normalized
+  }
+
+  const normalizeStoreAnchorId = (id) => {
+    const normalized = normalizeDomAnchorId(id)
+    return normalized === '0' ? 0 : normalized
+  }
+
   const register = (id) => {
-    store.commit('page/pushAnchors', id)
+    store.commit('page/pushAnchors', normalizeStoreAnchorId(id))
   }
 
   const index = (id, child = false) => {
     store.commit('page/pushNodes', {
-      id,
+      id: normalizeStoreAnchorId(id),
       label: selected.value,
       child,
       children: []
@@ -23,15 +44,17 @@ export default function useNavigator() {
   }
 
   const select = (id) => {
-    store.commit('page/setAnchor', Number(id))
-    store.commit('page/pushNodesExpanded', Number(id))
+    const normalized = normalizeStoreAnchorId(id)
+
+    store.commit('page/setAnchor', normalized)
+    store.commit('page/pushNodesExpanded', normalized)
   }
 
   const anchor = (id, toSelect = true) => {
     store.commit('page/setScrolling', false)
 
-    id = '' + id
-    const Anchor = document.getElementById(id)
+    const anchorId = normalizeDomAnchorId(id)
+    const Anchor = document.getElementById(anchorId)
 
     if (Anchor !== null && typeof Anchor === 'object') {
       const ScrollTarget = scroll.getScrollTarget(Anchor)
@@ -45,7 +68,7 @@ export default function useNavigator() {
     }
 
     if (toSelect) {
-      select(id)
+      select(anchorId)
     }
   }
 
@@ -60,12 +83,13 @@ export default function useNavigator() {
 
     for (let i = 0; i < anchors.length; i++) {
       const anchorId = anchors[i]
+      const domAnchorId = normalizeDomAnchorId(anchorId)
 
-      if (anchorId === 0) {
+      if (domAnchorId === '0') {
         continue
       }
 
-      const Anchor = document.getElementById(anchorId)
+      const Anchor = document.getElementById(domAnchorId)
       let AnchorOffsetTop = 20
       if (Anchor !== null && typeof Anchor === 'object') {
         AnchorOffsetTop = Anchor.offsetTop
@@ -78,24 +102,30 @@ export default function useNavigator() {
   }
 
   const navigate = (value, toAnchor = true) => {
+    const domAnchorId = normalizeDomAnchorId(value)
+    const currentRouteAnchorId = normalizeDomAnchorId(route.hash)
+
     if (toAnchor) {
-      if (('#' + value) === route.hash) {
-        anchor(value)
+      if (domAnchorId !== '' && domAnchorId === currentRouteAnchorId) {
+        anchor(domAnchorId)
         return
       } else if (value === null) {
-        anchor(selected.value, false)
+        anchor(store.state.page.anchor, false)
         return
       }
     }
 
-    router.push(route.path + '#' + value)
+    router.push({
+      path: route.path,
+      hash: domAnchorId === '' ? '' : `#${domAnchorId}`
+    })
 
     if (toAnchor) {
       if (Platform.is.desktop) {
-        anchor(value)
+        anchor(domAnchorId)
       } else {
         setTimeout(() => {
-          anchor(value)
+          anchor(domAnchorId)
         }, 600)
       }
     }

package/src/css/app.sass

@@ -1,3 +1,5 @@
+@import 'katex/dist/katex.min.css'
+
 /* --- Docsector Reader --- */
 @font-face
   font-family: "Fira Code Nerd Font"
@@ -187,6 +189,16 @@ body.body--dark
     display: inline
     line-height: 0.85em
 
+  .katex
+    color: inherit
+    max-width: 100%
+
+  .katex-display
+    max-width: 100%
+    overflow-x: auto
+    overflow-y: hidden
+    padding: 0.35rem 0.1rem
+
   a
     text-decoration: none
     outline: 0

package/src/pages/404Page.vue

@@ -3,12 +3,12 @@
   <q-page class="row" padding>
     <q-scroll-area class="content col text-center">
       <p>
-        <img src="sad.svg" style="width:30vw;max-width:150px;" />
+        <img src="/sad.svg" alt="404 illustration" style="width:30vw;max-width:150px;" />
       </p>
       <p class="text-faded">Sorry, nothing here...
         <strong>(404)</strong>
       </p>
-      <q-btn color="secondary" style="width:200px;" @click="$router.go(-1)">Go back</q-btn>
+      <q-btn color="secondary" style="width:200px;" @click="$router.push('/')">Go home</q-btn>
     </q-scroll-area>
   </q-page>
 </q-page-container>

package/src/pages/Homepage.en-US.md

@@ -7,9 +7,9 @@ Docsector Reader is a documentation rendering engine built with Vue 3, Quasar v2
 - [Getting Started](/guide/getting-started/overview/)
 - [Configuration](/guide/configuration/overview/)
 - [Pages and Routing](/guide/pages-and-routing/overview/)
-- [Components](/manual/components/d-page/overview/)
-- [Composables](/manual/composables/use-navigator/overview/)
-- [Store Modules](/manual/store/modules/overview/)
+- [Basic](/manual/basic/d-menu/overview/)
+- [Content](/manual/content/blocks/paragraphs/overview/)
+- [Structures](/manual/content/structures/books/overview/)
 
 ## About
 

package/src/pages/Homepage.pt-BR.md

@@ -7,9 +7,9 @@ Docsector Reader e um motor de documentacao construído com Vue 3, Quasar v2 e V
 - [Comecando](/guide/getting-started/overview/)
 - [Configuracao](/guide/configuration/overview/)
 - [Paginas e Rotas](/guide/pages-and-routing/overview/)
-- [Componentes](/manual/components/d-page/overview/)
-- [Composables](/manual/composables/use-navigator/overview/)
-- [Modulos de Store](/manual/store/modules/overview/)
+- [Básico](/manual/basic/d-menu/overview/)
+- [Conteúdo](/manual/content/blocks/paragraphs/overview/)
+- [Estruturas](/manual/content/structures/books/overview/)
 
 ## Sobre