@docsector/docsector-reader 0.3.3 → 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.3",
+  "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/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

@@ -245,7 +245,7 @@ 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 and the router from pre-bundling.