@docsector/docsector-reader 0.3.2 → 0.4.0

package/README.md

@@ -21,6 +21,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 ## ✨ Features
 
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
+- 🧩 **Mermaid Diagrams** — Native support for fenced ` ```mermaid ` blocks, with automatic dark/light theme switching
 - 🌍 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "0.3.2",
+  "version": "0.4.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,6 +70,7 @@
     "hjson": "^3.2.2",
     "markdown-it": "^13.0.1",
     "markdown-it-attrs": "^4.1.6",
+    "mermaid": "^11.0.0",
     "prismjs": "^1.27.0",
     "q-colorize-mixin": "^2.0.0-alpha.5"
   },

package/src/components/DMenu.vue

@@ -100,10 +100,7 @@ const getMenuItemHeaderLabel = (meta) => {
   const label = meta.menu.header.label
   if (label[0] === '.') { // Node path
     const path = `_.${meta.type}${label}._`
-    if (te(path)) {
-      return t(path)
-    }
-    return t(path, 'en-US')
+    return t(path)
   }
   return label // String raw
 }

package/src/components/DMenuItem.vue

@@ -29,7 +29,7 @@ const props = defineProps({
 
 const $q = useQuasar()
 const $route = useRoute()
-const { t, te } = useI18n()
+const { t } = useI18n()
 
 const getMenuItemHeaderBackground = () => {
   return $q.dark.isActive ? 'background-color: #1D1D1D !important' : 'background-color: #f5f5f5 !important'
@@ -37,22 +37,14 @@ const getMenuItemHeaderBackground = () => {
 
 const getMenuItemLabel = (item, index) => {
   const path = `_${item.path.replace(/_$/, '').replace(/\//g, '.')}._`
-  if (te(path)) {
-    return t(path)
-  } else {
-    return t(path, 'en-US')
-  }
+  return t(path)
 }
 
 const getMenuItemSubheader = (meta) => {
   const subheader = meta.menu.subheader
   const path = `_.${meta.type}${subheader}._`
 
-  if (te(path)) {
-    return t(path)
-  } else {
-    return t(path, 'en-US')
-  }
+  return t(path)
 }
 
 const getPageStatusText = (status) => {

package/src/components/DMermaidDiagram.vue

@@ -0,0 +1,103 @@
+<script setup>
+import { ref, onMounted, watch } from 'vue'
+import { useQuasar } from 'quasar'
+
+const props = defineProps({
+  content: {
+    type: String,
+    required: true
+  }
+})
+
+const $q = useQuasar()
+
+let _counter = 0
+const uid = `mermaid-${++_counter}-${Math.random().toString(36).slice(2, 7)}`
+
+const svg = ref('')
+const error = ref('')
+
+async function render () {
+  error.value = ''
+  svg.value = ''
+
+  try {
+    const mermaid = (await import('mermaid')).default
+
+    mermaid.initialize({
+      startOnLoad: false,
+      theme: $q.dark.isActive ? 'dark' : 'default'
+    })
+
+    const decoded = props.content
+      .replace(/&#123;/g, '{')
+      .replace(/&#125;/g, '}')
+      .replace(/&amp;/g, '&')
+
+    const { svg: rendered } = await mermaid.render(uid, decoded)
+    svg.value = rendered
+  } catch (e) {
+    error.value = e?.message || 'Mermaid render error'
+  }
+}
+
+onMounted(render)
+
+watch(() => $q.dark.isActive, render)
+</script>
+
+<template>
+  <div class="d-mermaid-diagram">
+    <div
+      v-if="svg"
+      class="d-mermaid-diagram__svg"
+      v-html="svg"
+    />
+    <div
+      v-else-if="error"
+      class="d-mermaid-diagram__error"
+    >
+      <pre>{{ error }}</pre>
+      <pre class="d-mermaid-diagram__source">{{ content }}</pre>
+    </div>
+    <div
+      v-else
+      class="d-mermaid-diagram__loading"
+    />
+  </div>
+</template>
+
+<style lang="sass">
+.d-mermaid-diagram
+  margin: 1rem 0
+  display: flex
+  justify-content: center
+
+  &__svg
+    svg
+      max-width: 100%
+      height: auto
+
+  &__error
+    width: 100%
+    padding: 0.75rem 1rem
+    border-left: 3px solid #e53935
+    background: rgba(229, 57, 53, 0.08)
+    font-size: 0.85em
+    pre
+      margin: 0
+
+  &__loading
+    width: 100%
+    min-height: 80px
+    opacity: 0.3
+    background: currentColor
+    border-radius: 4px
+    animation: mermaid-pulse 1.2s ease-in-out infinite
+
+@keyframes mermaid-pulse
+  0%, 100%
+    opacity: 0.15
+  50%
+    opacity: 0.3
+</style>

package/src/components/DPageSection.vue

@@ -11,6 +11,7 @@ import DH4 from './DH4.vue'
 import DH5 from './DH5.vue'
 import DH6 from './DH6.vue'
 import DPageSourceCode from './DPageSourceCode.vue'
+import DMermaidDiagram from './DMermaidDiagram.vue'
 
 const props = defineProps({
   id: {
@@ -82,6 +83,15 @@ const tokenized = computed(() => {
         case 'fence': {
           const info = element.info.split(' ')
           const language = info[0]
+
+          if (language === 'mermaid') {
+            tokens.push({
+              tag: 'mermaid',
+              content: element.content
+            })
+            break
+          }
+
           const filename = info[1] ? info[1].replace('filename=', '').replace(/"/g, '') : ''
 
           tokens.push({
@@ -229,6 +239,11 @@ const tokenized = computed(() => {
       :language="token.info"
       :filename="token.filename"
     />
+
+    <d-mermaid-diagram
+      v-else-if="token.tag === 'mermaid'"
+      :content="token.content"
+    />
   </template>
 </section>
 </template>

package/src/pages/guide/i18n-and-markdown.overview.en-US.md

@@ -54,6 +54,17 @@ Fenced code blocks support syntax highlighting via Prism.js:
 - `html` — HTML markup
 - `javascript` — JavaScript code
 
+### Mermaid Diagrams
+
+You can render Mermaid diagrams using fenced blocks with the `mermaid` language indicator. The diagrams automatically adapt to light and dark modes.
+
+```
+```mermaid
+flowchart TD
+  A[Start] --> B[End]
+```
+```
+
 ### Custom Attributes
 
 The `markdown-it-attrs` plugin enables custom attributes using `:attr;` syntax:

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

@@ -54,6 +54,17 @@ Blocos de código cercados suportam syntax highlighting via Prism.js:
 - `html` — Markup HTML
 - `javascript` — Código JavaScript
 
+### Diagramas Mermaid
+
+Você pode renderizar diagramas Mermaid usando blocos de código com o indicador de linguagem `mermaid`. Os diagramas se adaptam automaticamente aos modos claro e escuro.
+
+```
+```mermaid
+flowchart TD
+  A[Início] --> B[Fim]
+```
+```
+
 ### Atributos Customizados
 
 O plugin `markdown-it-attrs` permite atributos customizados usando sintaxe `:attr;`:

package/src/pages/index.js

@@ -239,6 +239,22 @@ export default {
     }
   },
 
+  '/components/d-mermaid-diagram': {
+    config: {
+      icon: 'account_tree',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DMermaidDiagram' },
+      'pt-BR': { title: 'DMermaidDiagram' }
+    }
+  },
+
   '/components/d-page-blockquote': {
     config: {
       icon: 'format_quote',

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

@@ -0,0 +1,31 @@
+## Overview
+
+`DMermaidDiagram` is an internal component responsible for rendering **Mermaid** diagrams. It intercepts code blocks fenced with the `mermaid` language indicator and renders them as SVG visuals instead of formatted text.
+
+The component uses lazy-loading — the `mermaid` library is only fetched when a diagram is present on the page, keeping the initial bundle size small.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `content` | `String` | Yes | — | The raw Mermaid definition syntax |
+
+## Features
+
+### Direct Rendering
+
+Diagrams are parsed and rendered directly into SVGs via the official `mermaid.render()` API. The SVGs are fully responsive.
+
+### Dark/Light Mode Aware
+
+The diagrams inherit their theme dynamically. When `$q.dark.isActive` toggles, `DMermaidDiagram` detects the change, re-initializes Mermaid with the new theme context, and entirely redraws the instance to match Docsector's overall appearance.
+
+### Error Handling
+
+If the provided syntax is invalid, the component gracefully catches the parsing error and displays a structured error block along with the raw source code.
+
+This guarantees the page will not break and aids during development.
+
+### HTML Entity Decoding
+
+Curly braces `{` and `}` are properly decoded before rendering, ensuring compatibility with Vue's i18n interpolation requirements while allowing Mermaid logic to function intact.

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

@@ -0,0 +1,29 @@
+## Visão geral
+
+O `DMermaidDiagram` é um componente interno responsável por renderizar diagramas **Mermaid**. Ele intercepta os blocos de código marcados com o indicador de linguagem `mermaid` e os renderiza como elementos SVG ao invés de texto puro.
+
+O componente utiliza _lazy-loading_ — a biblioteca `mermaid` apenas é baixada quando de fato existe um diagrama na página, mantendo o tamanho inicial do site otimizado.
+
+## Props
+
+| Prop | Tipo | Obrigatório | Valor padrão | Descrição |
+|------|------|----------|---------|-------------|
+| `content` | `String` | Sim | — | A sintaxe pura da definição do Mermaid |
+
+## Funcionalidades
+
+### Renderização Direta
+
+Os diagramas são lidos e renderizados diretamente em SVGs pela API oficial `mermaid.render()`. Os SVGs gerados são totalmente responsivos.
+
+### Adaptação aos Modos Claro/Escuro
+
+Os diagramas herdam a temática que você desejar. Quando o indicador `$q.dark.isActive` for alternado, O `DMermaidDiagram` rastreará tal mudança, re-inicializará um Mermaid com o novo contexto de tema e irá redesenhar toda a instância para espelhar a aparência visual geral do Docsector.
+
+### Tratamento de Falhas
+
+Se a sintaxe fornecida estiver incorreta, o componente elegantemente detecta a falha sem que a aplicação se quebre. Exibindo na tela, apenas para si, um bloco com erro e o código original abaixo com dicas do erro em desenvolvimento.
+
+### Decodificação de Entidades HTML
+
+Chaves numéricas de texto `{` e `}` tem seus devidos caracteres tratados antes do envio de renderização, garantindo harmonia entre os requisitos de visualização na extensão i18n padrão do Vue junto da estabilidade do código original desenhado para Mermaid em tempo-real.

package/src/pages/manual/components/d-mermaid-diagram.showcase.en-US.md

@@ -0,0 +1,33 @@
+## Flowchart
+
+```mermaid
+flowchart TD
+  A[Christmas] -->|Get money| B(Go shopping)
+  B --> C{Let me think}
+  C -->|One| D[Laptop]
+  C -->|Two| E[iPhone]
+  C -->|Three| F[fa:fa-car Car]
+```
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    Alice->>+John: Hello John, how are you?
+    Alice->>+John: John, can you hear me?
+    John-->>-Alice: Hi Alice, I can hear you!
+    John-->>-Alice: I feel great!
+```
+
+## State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+
+    Still --> Moving
+    Moving --> Still
+    Moving --> Crash
+    Crash --> [*]
+```

package/src/pages/manual/components/d-mermaid-diagram.showcase.pt-BR.md

@@ -0,0 +1,33 @@
+## Fluxograma
+
+```mermaid
+flowchart TD
+  A[Natal] -->|Ganha dinheiro| B(Ir às compras)
+  B --> C{Deixe-me pensar}
+  C -->|Um| D[Notebook]
+  C -->|Dois| E[iPhone]
+  C -->|Três| F[fa:fa-car Carro]
+```
+
+## Diagrama de Sequência
+
+```mermaid
+sequenceDiagram
+    Alice->>+John: Olá John, como você está?
+    Alice->>+John: John, consegue me ouvir?
+    John-->>-Alice: Oi Alice, consigo sim!
+    John-->>-Alice: Estou ótimo!
+```
+
+## Diagrama de Estado
+
+```mermaid
+stateDiagram-v2
+    [*] --> Parado
+    Parado --> [*]
+
+    Parado --> Movendo
+    Movendo --> Parado
+    Movendo --> Colisão
+    Colisão --> [*]
+```

package/src/quasar.factory.js

@@ -23,7 +23,8 @@
  * @param {Function} [options.extendViteConf] - Additional Vite config extension
  */
 
-import { readFileSync, existsSync } from 'fs'
+import { readFileSync, existsSync, rmSync } from 'fs'
+import { createHash } from 'crypto'
 import { resolve } from 'path'
 import HJSON from 'hjson'
 
@@ -57,6 +58,46 @@ function getPackageRoot (projectRoot) {
   return projectRoot
 }
 
+/**
+ * Create a Vite plugin that watches consumer content files (pages/index.js,
+ * i18n languages, etc.) and forces the Vite dep optimizer to re-run when
+ * they change.
+ *
+ * Why: The router module (`routes.js`) imports consumer content via the
+ * `pages` alias. Vite's dep optimizer pre-bundles the router with the
+ * consumer content inlined, but the optimizer cache hash is based on config
+ * and lockfile only — NOT on consumer source files. So when pages/index.js
+ * changes during development, the optimizer serves stale pre-bundled code
+ * until the cache is manually cleared.
+ *
+ * Fix: When pages/index.js changes, the watcher plugin clears the dep cache,
+ * sets an env flag, and restarts the server. On restart, the config reads the
+ * flag and sets `optimizeDeps.force = true`, which makes Vite generate a new
+ * browserHash — effectively busting the browser module cache.
+ */
+function createPagesWatchPlugin (projectRoot) {
+  const pagesIndex = resolve(projectRoot, 'src', 'pages', 'index.js')
+  return {
+    name: 'docsector-pages-watch',
+    configureServer (server) {
+      server.watcher.on('change', (changedPath) => {
+        if (changedPath === pagesIndex) {
+          server.config.logger.info(
+            '\\x1b[36m[docsector]\\x1b[0m pages/index.js changed — clearing dep cache and restarting...',
+            { timestamp: true }
+          )
+          // Signal the restarted config to force a new optimizer hash
+          process.env.__DOCSECTOR_FORCE_OPTIMIZE = '1'
+          // Delete the stale optimizer cache
+          const cacheDir = resolve(projectRoot, 'node_modules', '.q-cache')
+          rmSync(cacheDir, { recursive: true, force: true })
+          server.restart()
+        }
+      })
+    }
+  }
+}
+
 /**
  * Create the HJSON Vite plugin for loading .hjson files as ES modules.
  */
@@ -145,6 +186,7 @@ export function createQuasarConfig (options = {}) {
 
       vitePlugins: [
         createHjsonPlugin(),
+        createPagesWatchPlugin(projectRoot),
         ...vitePlugins
       ],
 
@@ -152,6 +194,32 @@ export function createQuasarConfig (options = {}) {
         viteConf.resolve = viteConf.resolve || {}
         viteConf.resolve.alias = viteConf.resolve.alias || {}
 
+        // When the pages watcher plugin triggers a restart, it sets this env
+        // flag so we force Vite to generate a fresh browserHash. This busts
+        // the browser's module cache for pre-bundled deps whose content changed.
+        viteConf.optimizeDeps = viteConf.optimizeDeps || {}
+        if (process.env.__DOCSECTOR_FORCE_OPTIMIZE) {
+          delete process.env.__DOCSECTOR_FORCE_OPTIMIZE
+          viteConf.optimizeDeps.force = true
+        }
+
+        // Include a hash of pages/index.js in the optimizer config so that
+        // Vite's configHash (and thus browserHash) changes whenever page
+        // definitions change. This prevents the browser from serving stale
+        // pre-bundled router modules from its module cache.
+        const pagesFile = resolve(projectRoot, 'src', 'pages', 'index.js')
+        if (existsSync(pagesFile)) {
+          const pagesHash = createHash('sha256')
+            .update(readFileSync(pagesFile))
+            .digest('hex')
+            .slice(0, 8)
+          viteConf.optimizeDeps.esbuildOptions = viteConf.optimizeDeps.esbuildOptions || {}
+          viteConf.optimizeDeps.esbuildOptions.define = {
+            ...(viteConf.optimizeDeps.esbuildOptions.define || {}),
+            __DOCSECTOR_PAGES_HASH__: JSON.stringify(pagesHash)
+          }
+        }
+
         // Deduplicate Vue ecosystem packages to prevent dual-instance issues.
         // When the package is installed from NPM, Vue, vue-router, vuex, etc.
         // can end up duplicated (one copy in consumer's node_modules, another
@@ -177,14 +245,18 @@ export function createQuasarConfig (options = {}) {
           ...(viteConf.optimizeDeps.include || []),
           'vue', 'vue-router', 'vuex', 'vue-i18n',
           'prismjs', 'markdown-it', 'markdown-it-attrs',
-          'hjson', 'q-colorize-mixin'
+          'hjson', 'q-colorize-mixin', 'mermaid'
         ]
 
-        // Exclude boot files from pre-bundling.
+        // Exclude boot files and the router from pre-bundling.
         // Boot files (especially boot/i18n) import the consumer's src/i18n/index.js
         // which uses import.meta.glob — a compile-time Vite directive that only
         // works in source files. If pre-bundled, the glob calls become dead code
         // and no i18n messages are loaded.
+        // The router is excluded because routes.js imports consumer content via
+        // the `pages` alias. If pre-bundled, consumer content gets embedded in
+        // the optimizer cache whose hash doesn't track source file changes,
+        // causing stale routes after editing pages/index.js.
         viteConf.optimizeDeps.exclude = [
           ...(viteConf.optimizeDeps.exclude || []),
           'boot/i18n', 'boot/store', 'boot/QZoom', 'boot/axios'