@docsector/docsector-reader 3.0.0 → 3.2.0

package/README.md

@@ -43,6 +43,7 @@ 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
@@ -54,6 +55,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📚 **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
 - 📐 **Responsive Subpage Toolbar** — Subpage actions align with the content column on desktop and dock to the bottom on mobile
+- ⬆️ **Reading Progress Back to Top** — Documentation subpages can show a floating back-to-top control with circular reading progress that stays above the mobile subpage toolbar
 - 🏷️ **Status Badges** — Mark pages as `done`, `draft`, `empty`, or `new` with visual indicators
 - ✏️ **Edit on GitHub** — Direct links to edit pages on your repository
 - 🧭 **Robust Edit Link Mapping** — Normalizes route paths (including trailing slashes) into `page.subpage.locale.md` source files for reliable GitHub edit URLs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.0.0",
+  "version": "3.2.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",
@@ -70,8 +70,10 @@
     "axios": "^1.7.7",
     "core-js": "^3.6.5",
     "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"

package/src/components/DPage.vue

@@ -5,6 +5,7 @@ import { useRoute, useRouter } from 'vue-router'
 import { useQuasar } from 'quasar'
 
 import useNavigator from '../composables/useNavigator'
+import { getReadingProgressState } from '../composables/useReadingProgress'
 
 import DPageAnchor from './DPageAnchor.vue'
 import DPageMeta from './DPageMeta.vue'
@@ -20,6 +21,10 @@ const props = defineProps({
   disableNav: {
     type: Boolean,
     default: false
+  },
+  showBackToTopControl: {
+    type: Boolean,
+    default: false
   }
 })
 
@@ -29,6 +34,26 @@ const submenu = ref(null)
 const pageMinHeight = ref('calc(100vh - 86px)')
 const submenuHeight = ref('36px')
 const pageBottomInset = ref('0px')
+const readingProgress = ref(getReadingProgressState())
+
+const getPageScrollContainer = () => {
+  return pageScrollArea.value?.$el?.querySelector('.q-scrollarea__container') || null
+}
+
+const syncReadingProgress = (scrollTop = null) => {
+  const container = getPageScrollContainer()
+
+  if (!container) {
+    readingProgress.value = getReadingProgressState()
+    return
+  }
+
+  readingProgress.value = getReadingProgressState({
+    scrollTop: scrollTop ?? container.scrollTop,
+    scrollHeight: container.scrollHeight,
+    clientHeight: container.clientHeight
+  })
+}
 
 const updatePageMinHeight = () => {
   const pageContainerEl = pageContainer.value?.$el || pageContainer.value
@@ -47,6 +72,7 @@ const updatePageMinHeight = () => {
   pageMinHeight.value = `calc(100vh - ${totalOffset}px)`
   submenuHeight.value = `${Math.max(36, Math.round(measuredSubmenuHeight))}px`
   pageBottomInset.value = isMobile ? submenuHeight.value : '0px'
+  syncReadingProgress()
 }
 
 const schedulePageMinHeightUpdate = () => {
@@ -80,6 +106,12 @@ const main = computed(() => {
       return 'overview'
   }
 })
+const shouldShowBackToTopControl = computed(() => {
+  return props.showBackToTopControl && readingProgress.value.hasOverflow && readingProgress.value.isVisible
+})
+const backToTopRightOffset = computed(() => {
+  return layoutMeta.value && !$q.screen.lt.md ? '332px' : '24px'
+})
 
 const toggleSectionsTree = () => {
   layoutMeta.value = !layoutMeta.value
@@ -133,10 +165,7 @@ const resetPageScroll = () => {
   if (pageScrollArea.value !== null) {
     pageScrollArea.value.setScrollPosition('vertical', 0, 0)
   }
-}
-
-const getPageScrollContainer = () => {
-  return pageScrollArea.value?.$el?.querySelector('.q-scrollarea__container') || null
+  syncReadingProgress(0)
 }
 
 const isEditableTarget = (target) => {
@@ -208,6 +237,15 @@ const handleMainScrollKeys = (event) => {
   container.scrollTop = nextTop
 }
 
+const handlePageScroll = (scrollState) => {
+  scrolling(scrollState)
+  syncReadingProgress(scrollState?.position?.top)
+}
+
+const scrollToTop = () => {
+  navigate(0)
+}
+
 onMounted(() => {
   window.addEventListener('keydown', handleMainScrollKeys)
   window.addEventListener('resize', schedulePageMinHeightUpdate)
@@ -236,6 +274,7 @@ onBeforeUnmount(() => {
 watch(() => route.fullPath, () => {
   nextTick(() => {
     schedulePageMinHeightUpdate()
+    syncReadingProgress(0)
   })
 })
 </script>
@@ -292,10 +331,38 @@ watch(() => route.fullPath, () => {
         <slot />
       </div>
       <d-page-meta v-if="!disableNav" />
-      <q-scroll-observer @scroll="scrolling" :debounce="300" />
+      <q-scroll-observer @scroll="handlePageScroll" :debounce="300" />
     </q-scroll-area>
   </q-page>
 
+  <div
+    v-if="shouldShowBackToTopControl"
+    class="d-back-to-top"
+    :style="{ '--d-back-to-top-right': backToTopRightOffset }"
+  >
+    <q-circular-progress
+      class="d-back-to-top__progress"
+      :value="readingProgress.progressPercent"
+      size="58px"
+      :thickness="0.16"
+      color="primary"
+      track-color="grey-5"
+    />
+    <q-btn
+      class="d-back-to-top__button"
+      round
+      dense
+      unelevated
+      color="dark"
+      text-color="white"
+      icon="north"
+      :aria-label="$t('system.backToTop')"
+      @click="scrollToTop"
+    >
+      <q-tooltip anchor="top middle" self="bottom middle" :offset="[10, 10]">{{ $t('system.backToTop') }}</q-tooltip>
+    </q-btn>
+  </div>
+
   <q-drawer elevated show-if-above side="right" v-model="layoutMeta">
     <d-page-anchor id="anchor" />
   </q-drawer>
@@ -321,6 +388,25 @@ watch(() => route.fullPath, () => {
 #page
   min-height: var(--d-page-min-height, calc(100vh - 86px)) !important
 
+.d-back-to-top
+  position: fixed
+  right: var(--d-back-to-top-right, 24px)
+  bottom: calc(24px + var(--d-page-bottom-inset, 0px) + env(safe-area-inset-bottom, 0px))
+  width: 58px
+  height: 58px
+  z-index: 1200
+  filter: drop-shadow(0 8px 18px rgba(0,0,0,0.2))
+
+  .d-back-to-top__progress,
+  .d-back-to-top__button
+    position: absolute
+    inset: 0
+
+  .d-back-to-top__button
+    margin: auto
+    width: 40px
+    height: 40px
+
 #scroll-container
   width: 100%
   max-width: 1200px
@@ -425,4 +511,12 @@ body.mobile.body--dark
 body.mobile
   .q-drawer--right
     background: rgba(255, 255, 255, 0.7)
+
+body.body--light
+  .d-back-to-top__progress
+    color: var(--q-primary)
+
+body.body--dark
+  .d-back-to-top__progress
+    color: #58d1a8
 </style>

package/src/components/DSubpage.vue

@@ -22,7 +22,7 @@ const id = computed(() => {
 </script>
 
 <template>
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-page-bar />
     <hr />

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

@@ -1,5 +1,7 @@
 import MarkdownIt from 'markdown-it'
 import attrs from 'markdown-it-attrs'
+import katex from 'katex'
+import texmath from 'markdown-it-texmath'
 
 const ALERT_MESSAGE_TYPES = new Set([
   'note',
@@ -12,6 +14,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 +106,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 +305,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 +334,9 @@ const createMarkdownBlockParser = () => {
 }
 
 const createMarkdownInlineParser = () => {
-  return new MarkdownIt({
+  return installMathSupport(new MarkdownIt({
     html: true
-  })
+  }))
 }
 
 const normalizePageSectionSource = (source = '') => {
@@ -444,6 +464,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
@@ -519,6 +544,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 +606,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/useReadingProgress.js

@@ -0,0 +1,46 @@
+export const DEFAULT_READING_PROGRESS_THRESHOLD = 0.12
+
+const toFiniteNumber = (value) => {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized : 0
+}
+
+const clamp = (value, min, max) => {
+  return Math.min(max, Math.max(min, value))
+}
+
+export function getReadingProgressState({
+  scrollTop = 0,
+  scrollHeight = 0,
+  clientHeight = 0,
+  visibilityThreshold = DEFAULT_READING_PROGRESS_THRESHOLD
+} = {}) {
+  const normalizedClientHeight = Math.max(0, toFiniteNumber(clientHeight))
+  const normalizedScrollHeight = Math.max(0, toFiniteNumber(scrollHeight))
+  const maxScrollTop = Math.max(0, normalizedScrollHeight - normalizedClientHeight)
+
+  if (maxScrollTop === 0) {
+    return {
+      hasOverflow: false,
+      maxScrollTop: 0,
+      scrollTop: 0,
+      progressPercent: 0,
+      visibleOffset: 0,
+      isVisible: false
+    }
+  }
+
+  const normalizedScrollTop = clamp(toFiniteNumber(scrollTop), 0, maxScrollTop)
+  const normalizedThreshold = clamp(toFiniteNumber(visibilityThreshold), 0, 1)
+  const visibleOffset = Math.round(maxScrollTop * normalizedThreshold)
+  const progressPercent = Math.round((normalizedScrollTop / maxScrollTop) * 100)
+
+  return {
+    hasOverflow: true,
+    maxScrollTop,
+    scrollTop: normalizedScrollTop,
+    progressPercent,
+    visibleOffset,
+    isVisible: normalizedScrollTop >= visibleOffset && normalizedScrollTop > 0
+  }
+}

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/guide/i18n-and-markdown.overview.en-US.md

@@ -61,6 +61,25 @@ You can render Mermaid diagrams using fenced blocks with the `mermaid` language
 ```
 ```mermaid
 flowchart TD
+  A[Start] --> B[End]
+```
+```
+
+### Math and TeX
+
+Docsector supports KaTeX-style math in standard Markdown flows, including paragraphs, alerts, and expandable content.
+
+Use single dollar delimiters for inline math such as $E = mc^2$.
+
+Use double dollar delimiters for display math:
+
+```markdown
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+Math delimiters remain literal inside inline code and fenced code blocks, so syntax examples can be documented without rendering the equation.
 
 ### GitHub Alerts
 
@@ -75,9 +94,6 @@ Docsector also supports GitHub-style alert blockquotes:
 
 Supported types are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`.
 Regular blockquotes (without `[!TYPE]`) continue to work as normal.
-  A[Start] --> B[End]
-```
-```
 
 ### Custom Attributes
 

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

@@ -65,6 +65,22 @@ flowchart TD
 ```
 ```
 
+### Math e TeX
+
+O Docsector suporta fórmulas com KaTeX nos fluxos normais de Markdown, incluindo parágrafos, alertas e conteúdo expansível.
+
+Use delimitadores com um dólar para fórmulas inline, como $E = mc^2$.
+
+Use delimitadores com dois dólares para fórmulas em bloco:
+
+```markdown
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+Os delimitadores matemáticos permanecem literais dentro de código inline e fenced code, então exemplos de sintaxe podem ser documentados sem renderizar a equação.
+
 ### Alertas do GitHub
 
 O Docsector tambem suporta blockquotes de alerta no estilo do GitHub:

package/src/pages/manual/components/d-page.overview.en-US.md

@@ -9,6 +9,7 @@ Every documentation page is rendered inside a `DPage` instance.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `disableNav` | `Boolean` | `false` | Hides the DPageMeta navigation footer |
+| `showBackToTopControl` | `Boolean` | `false` | Enables the floating back-to-top control with circular reading progress |
 
 ## Template Structure
 
@@ -46,6 +47,8 @@ DPage reads the route's `meta.subpages` configuration to determine which tabs to
 
 DPage resets the scroll position on route changes via `router.beforeEach`. The scroll observer monitors vertical scroll position and updates the anchor selection via the `useNavigator` composable.
 
+When `showBackToTopControl` is enabled, DPage also derives reading progress from the same scroll container. The floating control stays hidden at the top, appears after a small amount of scroll, shows circular progress, and returns to anchor `0` when clicked.
+
 ## Store Integration
 
 DPage reads from and writes to several Vuex store modules:

package/src/pages/manual/components/d-page.overview.pt-BR.md

@@ -9,6 +9,7 @@ Toda página de documentação é renderizada dentro de uma instância de `DPage
 | Prop | Tipo | Padrão | Descrição |
 |------|------|--------|-----------|
 | `disableNav` | `Boolean` | `false` | Oculta o rodapé de navegação DPageMeta |
+| `showBackToTopControl` | `Boolean` | `false` | Habilita o controle flutuante de voltar ao topo com progresso circular de leitura |
 
 ## Estrutura do Template
 
@@ -46,6 +47,8 @@ DPage lê a configuração `meta.subpages` da rota para determinar quais abas ex
 
 DPage reseta a posição de scroll nas mudanças de rota via `router.beforeEach`. O observador de scroll monitora a posição vertical e atualiza a seleção de âncora via composable `useNavigator`.
 
+Quando `showBackToTopControl` está habilitada, DPage também deriva o progresso de leitura a partir da mesma área de scroll. O controle flutuante fica oculto no topo, aparece após uma pequena rolagem, exibe progresso circular e retorna para a âncora `0` ao ser clicado.
+
 ## Integração com Store
 
 DPage lê e escreve em vários módulos da Vuex store:

package/src/pages/manual/components/d-subpage.overview.en-US.md

@@ -9,7 +9,7 @@ DSubpage generates a deterministic numeric ID from the current route path using
 ## Template
 
 ```html
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-h1 :id="0" />
   </header>
@@ -54,3 +54,7 @@ DSubpage is automatically used by the router for all documentation pages. You do
 - `DSubpage` **uses** `DPage` as its container
 - `DPage` handles layout (scroll, toolbar, drawer)
 - `DSubpage` handles content composition (H1 + sections)
+
+## Built-in Back to Top Control
+
+Routed documentation subpages enable DPage's floating back-to-top control automatically. The control is only shown when the content actually overflows, becomes visible after the reader scrolls a little, and visualizes the current reading progress with a circular indicator.

package/src/pages/manual/components/d-subpage.overview.pt-BR.md

@@ -9,7 +9,7 @@ DSubpage gera um ID numérico determinístico a partir do caminho da rota atual
 ## Template
 
 ```html
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-h1 :id="0" />
   </header>
@@ -54,3 +54,7 @@ DSubpage é usado automaticamente pelo roteador para todas as páginas de docume
 - `DSubpage` **usa** `DPage` como container
 - `DPage` cuida do layout (scroll, toolbar, drawer)
 - `DSubpage` cuida da composição de conteúdo (H1 + seções)
+
+## Controle Integrado de Voltar ao Topo
+
+As sub-páginas de documentação roteadas habilitam automaticamente o controle flutuante de voltar ao topo do DPage. O controle só é exibido quando o conteúdo realmente tem overflow, fica visível após uma pequena rolagem do leitor e mostra o progresso atual de leitura com um indicador circular.