@docsector/docsector-reader 3.1.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

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

package/package.json

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