@md-plugins/quasar-app-extension-q-press 0.1.0-beta.19 → 0.1.0-beta.20

package/README.md

@@ -4,7 +4,7 @@ The Ultimate Markdown Solution for the Quasar Framework.
 
 See the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpress/overview) for more information.
 
-> Current beta release: `0.1.0-beta.19`.
+> Current beta release: `0.1.0-beta.20`.
 >
 > Q-Press currently targets Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.33`. TypeScript processing is required.
 

package/dist/install.js

@@ -24,6 +24,7 @@ export default defineInstallScript(async (api) => {
     }
     api.extendPackageJson({
         dependencies: {
+            mermaid: '^11.15.0',
             shiki: '^4.1.0',
         },
     });

package/dist/templates/init/src/_q-press/components/MarkdownMermaid.vue

@@ -0,0 +1,123 @@
+<template>
+  <div class="markdown-mermaid q-my-md">
+    <div
+      v-if="errorMessage"
+      class="markdown-mermaid__error"
+      role="alert"
+    >
+      {{ errorMessage }}
+    </div>
+    <div
+      v-else-if="isRendering"
+      class="markdown-mermaid__loading"
+    >
+      Rendering diagram...
+    </div>
+    <div
+      ref="containerRef"
+      class="markdown-mermaid__diagram"
+    ></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { uid, useQuasar } from 'quasar'
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+
+const props = defineProps<{
+  code: string
+}>()
+
+const $q = useQuasar()
+const containerRef = ref<HTMLElement | null>(null)
+const errorMessage = ref('')
+const isRendering = ref(false)
+
+let disposed = false
+let renderRequest = 0
+
+async function renderDiagram(): Promise<void> {
+  if (import.meta.env.QUASAR_CLIENT !== true || containerRef.value === null) {
+    return
+  }
+
+  const requestId = ++renderRequest
+
+  errorMessage.value = ''
+  isRendering.value = true
+
+  await nextTick()
+
+  try {
+    const { default: mermaid } = await import('mermaid')
+
+    mermaid.initialize({
+      securityLevel: 'strict',
+      startOnLoad: false,
+      theme: $q.dark.isActive === true ? 'dark' : 'default',
+    })
+
+    const { svg, bindFunctions } = await mermaid.render(`markdown-mermaid-${uid()}`, props.code)
+
+    if (disposed === true || requestId !== renderRequest || containerRef.value === null) {
+      return
+    }
+
+    containerRef.value.innerHTML = svg
+    bindFunctions?.(containerRef.value)
+  } catch (error) {
+    if (disposed === false && requestId === renderRequest) {
+      errorMessage.value = error instanceof Error ? error.message : 'Unable to render diagram.'
+    }
+  } finally {
+    if (disposed === false && requestId === renderRequest) {
+      isRendering.value = false
+    }
+  }
+}
+
+onMounted(() => {
+  void renderDiagram()
+})
+
+watch(
+  () => [props.code, $q.dark.isActive] as const,
+  () => {
+    void renderDiagram()
+  },
+)
+
+onBeforeUnmount(() => {
+  disposed = true
+})
+</script>
+
+<style lang="scss">
+.markdown-mermaid {
+  border: 1px solid var(--q-separator-color);
+  border-radius: 8px;
+  overflow-x: auto;
+  padding: 1rem;
+
+  &__diagram {
+    min-width: 100%;
+    text-align: center;
+
+    svg {
+      max-width: 100%;
+      height: auto;
+    }
+  }
+
+  &__error {
+    color: var(--q-negative);
+    font-family: monospace;
+    white-space: pre-wrap;
+  }
+
+  &__loading {
+    color: var(--q-secondary);
+    font-style: italic;
+  }
+}
+</style>

package/dist/templates/init/src/_q-press/css/code-theme.scss

@@ -4,6 +4,10 @@
   overflow: auto;
   border-radius: inherit;
 
+  &.twoslash {
+    overflow: visible;
+  }
+
   code {
     display: block;
     padding: 16px;
@@ -39,6 +43,10 @@
     display: inline-block;
     width: 100%;
   }
+
+  &:has(.twoslash-query-persisted) > code {
+    padding-bottom: calc(16px + 2.2em);
+  }
 }
 
 .c-line {
@@ -165,6 +173,10 @@
     transform: translateY(1.5em);
   }
 
+  .twoslash-query-persisted {
+    display: inline-block;
+  }
+
   .twoslash-hover:hover .twoslash-popup-container,
   .twoslash-error-hover:hover .twoslash-popup-container,
   .twoslash-query-persisted .twoslash-popup-container,

package/dist/templates/init/src/markdown/getting-started/introduction.md

@@ -23,6 +23,7 @@ The core Markdown-it plugins and direct Vite plugins work in Vue/Vite projects a
 - **Title Extraction**: Extract the first header in Markdown as the page title.
 - **Script Imports**: Extract and process **<script import>** blocks from Markdown.
 - **Code Block Enhancements**: Enhance code block rendering with syntax highlighting, tabs, and more.
+- **Mermaid Diagrams**: Render Mermaid fenced code blocks as client-side diagrams.
 - **Custom Styling**: Apply custom styles to your Markdown content for a more refined look.
 - **Integration**: Easily integrate with other tools and platforms to streamline your workflow.
 
@@ -59,6 +60,7 @@ Here are some examples of what you can achieve with Markdown Plugins:
 - **Title Extraction**: Extract the first header in Markdown as the page title.
 - **Script Imports**: Extract and process `<script import>` blocks from Markdown.
 - **Code Block Enhancements**: Enhance code block rendering with syntax highlighting, tabs, and more.
+- **Mermaid Diagrams**: Add flowcharts, sequence diagrams, and other Mermaid diagrams to Markdown pages.
 
 ## Support
 

package/dist/templates/init/src/markdown/md-plugins/codeblocks/overview.md

@@ -68,16 +68,30 @@ console.log('Hello, world!')
 
 ### Code Block with TwoSlash
 
-Add the `twoslash` attribute to TypeScript or JavaScript examples when you want inferred type information, compiler diagnostics, or `^?` query output.
+Add the `twoslash` attribute to TypeScript or JavaScript examples when you want inferred type information, compiler diagnostics, or query output. Hover an identifier in the example below to see the type tooltip.
 
 ```ts [twoslash]
 const count = 1
-//    ^?
+const label = count.toFixed(0)
 ```
 
 ````markup
 ```ts [twoslash]
 const count = 1
+const label = count.toFixed(0)
+```
+````
+
+If you add a `// ^?` query marker, TwoSlash renders that query result persistently below the matching expression. That is useful for teaching types directly in the page, while normal identifier details remain hover-based.
+
+```ts [twoslash]
+const selectedIcon = 'event' as const
+//    ^?
+```
+
+````markup
+```ts [twoslash]
+const selectedIcon = 'event' as const
 //    ^?
 ```
 ````

package/dist/templates/init/src/markdown/md-plugins/mermaid/advanced.md

@@ -0,0 +1,69 @@
+---
+title: Mermaid Advanced Topics
+desc: Mermaid plugin options and integration details.
+---
+
+The Mermaid plugin is small, but it has two different integration paths:
+
+- **Component mode** is the Q-Press default. It emits `MarkdownMermaid` and lets Vue render Mermaid on the client.
+- **Pre mode** emits a plain `<pre class="mermaid">` block for custom MarkdownIt pipelines.
+
+## Options
+
+| Option          | Type                   | Default              | Description                                  |
+| --------------- | ---------------------- | -------------------- | -------------------------------------------- |
+| `languages`     | `string[]`             | `['mermaid', 'mmd']` | Fence languages treated as Mermaid diagrams. |
+| `renderMode`    | `'component' \| 'pre'` | `'component'`        | Output mode for diagrams.                    |
+| `componentName` | `string`               | `'MarkdownMermaid'`  | Component used in component mode.            |
+| `codeProp`      | `string`               | `'code'`             | Component prop that receives Mermaid source. |
+| `preClass`      | `string`               | `'mermaid'`          | CSS class used in pre mode.                  |
+| `pageScripts`   | `string[]`             | Q-Press import       | Imports added to generated Vue pages.        |
+
+## Component Mode
+
+Use component mode when Markdown output is compiled into Vue components:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { mermaidPlugin } from '@md-plugins/md-plugin-mermaid'
+
+const md = new MarkdownIt()
+md.use(mermaidPlugin, {
+  componentName: 'MarkdownMermaid',
+  codeProp: 'code',
+})
+```
+
+Component mode adds this import to the generated page when a Mermaid fence is found:
+
+```ts
+import MarkdownMermaid from '@/.q-press/components/MarkdownMermaid.vue'
+```
+
+## Pre Mode
+
+Use pre mode when your app has its own Mermaid bootstrapping:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { mermaidPlugin } from '@md-plugins/md-plugin-mermaid'
+
+const md = new MarkdownIt()
+md.use(mermaidPlugin, {
+  renderMode: 'pre',
+  preClass: 'mermaid',
+})
+```
+
+Then run Mermaid after the HTML is mounted:
+
+```ts
+import mermaid from 'mermaid'
+
+mermaid.initialize({ startOnLoad: false })
+await mermaid.run({ querySelector: '.mermaid' })
+```
+
+## Security
+
+The Q-Press `MarkdownMermaid` component initializes Mermaid with `securityLevel: 'strict'`. Keep that unless you have a specific reason to allow looser rendering.

package/dist/templates/init/src/markdown/md-plugins/mermaid/overview.md

@@ -0,0 +1,73 @@
+---
+title: Mermaid Plugin
+desc: Render Mermaid diagrams from fenced code blocks.
+---
+
+The Mermaid plugin turns `mermaid` and `mmd` fenced code blocks into diagrams. In Q-Press and `viteMdPlugin`, Mermaid diagrams render through the generated `MarkdownMermaid` Vue component so diagrams stay client-side and SSR-safe.
+
+## Example
+
+```mermaid
+flowchart LR
+  Markdown[Markdown file] --> Plugin[md-plugin-mermaid]
+  Plugin --> Component[MarkdownMermaid]
+  Component --> Diagram[Rendered diagram]
+```
+
+## Markdown
+
+````markdown
+```mermaid
+flowchart LR
+  Markdown[Markdown file] --> Plugin[md-plugin-mermaid]
+  Plugin --> Component[MarkdownMermaid]
+  Component --> Diagram[Rendered diagram]
+```
+````
+
+## Installation
+
+You can install the Mermaid plugin using npm, yarn, pnpm, or bun:
+
+```tabs
+<<| bash pnpm |>>
+pnpm add @md-plugins/md-plugin-mermaid mermaid
+<<| bash bun |>>
+bun add @md-plugins/md-plugin-mermaid mermaid
+<<| bash yarn |>>
+yarn add @md-plugins/md-plugin-mermaid mermaid
+<<| bash npm |>>
+npm install @md-plugins/md-plugin-mermaid mermaid
+```
+
+Q-Press installs `mermaid` for generated documentation projects. Direct MarkdownIt users only need `mermaid` if they render diagrams in the browser.
+
+## Basic Usage
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { mermaidPlugin } from '@md-plugins/md-plugin-mermaid'
+
+const md = new MarkdownIt()
+md.use(mermaidPlugin)
+```
+
+The default output is a Vue component:
+
+```html
+<MarkdownMermaid :code="diagramSource"></MarkdownMermaid>
+```
+
+If you own the browser initialization yourself, use plain pre mode:
+
+```ts
+md.use(mermaidPlugin, {
+  renderMode: 'pre',
+})
+```
+
+That renders Mermaid-compatible HTML:
+
+```html
+<pre class="mermaid"><code>flowchart LR...</code></pre>
+```

package/dist/templates/init/src/markdown/vite-plugins/vite-md-plugin/advanced.md

@@ -11,7 +11,7 @@ The `viteMdPlugin` is a powerful tool for integrating Markdown processing into y
 
 ```ts
 import { Plugin } from 'vite'
-import { Options } from 'markdown-it'
+import MarkdownIt, { Options } from 'markdown-it'
 import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote'
 import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks'
 import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter'
@@ -19,21 +19,27 @@ import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers'
 import { ImagePluginOptions } from '@md-plugins/md-plugin-image'
 import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode'
 import { LinkPluginOptions } from '@md-plugins/md-plugin-link'
+import { MermaidPluginOptions } from '@md-plugins/md-plugin-mermaid'
 import { TablePluginOptions } from '@md-plugins/md-plugin-table'
 
+type MarkdownItPlugin = (md: MarkdownIt, ...params: any[]) => void
+type MarkdownItPluginEntry = MarkdownItPlugin | [MarkdownItPlugin, ...any[]]
+
 interface MarkdownOptions extends Options {
   html?: boolean
   linkify?: boolean
   typographer?: boolean
   breaks?: boolean
-  blockquote?: BlockquotePluginOptions
-  codeblocks?: CodeblockPluginOptions
-  frontmatter?: FrontmatterPluginOptions
-  headers?: HeadersPluginOptions | boolean
-  image?: ImagePluginOptions
-  inlinecode?: InlineCodePluginOptions
-  link?: LinkPluginOptions
-  table?: TablePluginOptions
+  blockquotePlugin?: BlockquotePluginOptions
+  codeblockPlugin?: CodeblockPluginOptions
+  frontmatterPlugin?: FrontmatterPluginOptions
+  headersPlugin?: HeadersPluginOptions | boolean
+  imagePlugin?: ImagePluginOptions
+  inlineCodePlugin?: InlineCodePluginOptions
+  linkPlugin?: LinkPluginOptions
+  mermaidPlugin?: MermaidPluginOptions
+  tablePlugin?: TablePluginOptions
+  markdownItPlugins?: MarkdownItPluginEntry[]
 }
 
 interface MenuItem {
@@ -128,6 +134,59 @@ export default defineConfig({
 })
 ```
 
+### Using Other Markdown-It Plugins
+
+The `viteMdPlugin` already includes the md-plugins used by Q-Press, plus inserted text support for `++text++`. If you need additional Markdown-it syntax, install the plugin and pass it through `config.markdownItPlugins`.
+
+```tabs
+<<| bash pnpm |>>
+pnpm add markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+<<| bash bun |>>
+bun add markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+<<| bash yarn |>>
+yarn add markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+<<| bash npm |>>
+npm install markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+```
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import markdownItFootnote from 'markdown-it-footnote'
+import markdownItMark from 'markdown-it-mark'
+import markdownItSub from 'markdown-it-sub'
+import markdownItSup from 'markdown-it-sup'
+import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    viteMdPlugin({
+      path: './src/markdown',
+      menu: [],
+      config: {
+        markdownItPlugins: [
+          markdownItMark, // ==highlight==
+          markdownItSub, // H~2~O
+          markdownItSup, // E=mc^2^
+          markdownItFootnote, // footnote references
+        ],
+      },
+    }),
+  ],
+})
+```
+
+If you own a raw MarkdownIt instance instead of using `viteMdPlugin`, wire the plugins directly:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import markdownItMark from 'markdown-it-mark'
+
+const md = new MarkdownIt()
+md.use(markdownItMark)
+```
+
 ### Quasar Framework Configuration
 
 If you’re using the Quasar Framework with Vite, additional configuration is needed to enable support for `.md` files:
@@ -210,55 +269,26 @@ export interface MenuItem {
 #### `config`
 
 - **Type**: `MarkdownOptions`
-- **Description**: Additional configuration options for the Markdown processing.
-
-````ts
-import { Options } from 'markdown-it';
-import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote';
-import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks';
-import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter';
-import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers';
-import { ImagePluginOptions } from '@md-plugins/md-plugin-image';
-import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode';
-import { LinkPluginOptions } from '@md-plugins/md-plugin-link';
-import { TablePluginOptions } from '@md-plugins/md-plugin-table';
-
-interface MarkdownOptions extends Options {
-    html?: boolean;
-    linkify?: boolean;
-    typographer?: boolean;
-    breaks?: boolean;
-    blockquote?: BlockquotePluginOptions;
-    codeblocks?: CodeblockPluginOptions;
-    frontmatter?: FrontmatterPluginOptions;
-    headers?: HeadersPluginOptions | boolean;
-    image?: ImagePluginOptions;
-    inlinecode?: InlineCodePluginOptions;
-    link?: LinkPluginOptions;
-    table?: TablePluginOptions;
-}
-```
+- **Description**: Additional configuration options for the Markdown processor and bundled md-plugins.
 
-### Example Configuration
+Use `config.markdownItPlugins` for extra Markdown-it syntax that md-plugins does not bundle by default. Use `config.mermaidPlugin` to customize Mermaid rendering.
 
-Here is an example of how you can configure the `viteMdPlugin` with custom options:
-
-```typescript
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
+```ts
 import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
-
-const menu = [
-  { title: 'Home', path: '/' },
-  { title: 'Guide', path: '/guide/' },
-  { title: 'API', path: '/api/' },
-]
-const basePath = '/docs'
-
-export default defineConfig({
-  plugins: [vue(), viteMdPlugin(basePath, menu)],
+import markdownItMark from 'markdown-it-mark'
+
+viteMdPlugin({
+  path: './src/markdown',
+  menu: [],
+  config: {
+    markdownItPlugins: [markdownItMark],
+    mermaidPlugin: {
+      renderMode: 'component',
+      componentName: 'MarkdownMermaid',
+    },
+  },
 })
-````
+```
 
 ### Using the Plugin
 

package/dist/templates/init/src/markdown/vite-plugins/vite-md-plugin/overview.md

@@ -31,6 +31,7 @@ The `viteMdPlugin` is built on top of the following plugins:
 | `@md-plugins/md-plugin-inlinecode`  | Adds a custom class to inline code blocks for styling.                  | [README](packages/md-plugin-inlinecode/README.md)  | [Docs](/md-plugins/inline-code/overview) |
 | `@md-plugins/md-plugin-imports`     | Extracts and processes `<script import>` blocks from Markdown.          | [README](packages/md-plugin-imports/README.md)     | [Docs](/md-plugins/imports/overview)     |
 | `@md-plugins/md-plugin-link`        | Converts Markdown links into Vue components for SPA-friendly routing.   | [README](packages/md-plugin-link/README.md)        | [Docs](/md-plugins/link/overview)        |
+| `@md-plugins/md-plugin-mermaid`     | Renders Mermaid fenced code blocks as diagrams.                         | [README](packages/md-plugin-mermaid/README.md)     | [Docs](/md-plugins/mermaid/overview)     |
 | `@md-plugins/md-plugin-table`       | Adds custom classes and attributes to Markdown tables.                  | [README](packages/md-plugin-table/README.md)       | [Docs](/md-plugins/table/overview)       |
 | `@md-plugins/md-plugin-title`       | Extracts the first header in Markdown as the page title.                | [README](packages/md-plugin-title/README.md)       | [Docs](/md-plugins/title/overview)       |
 | `@md-plugins/md-plugin-frontmatter` | Extracts and processes frontmatter content from Markdown files.         | [README](packages/md-plugin-frontmatter/README.md) | [Docs](/md-plugins/frontmatter/overview) |

package/dist/templates/init/src/siteConfig/index.ts

@@ -235,6 +235,13 @@ const mdPluginsMenu: SiteMenuItem = {
         { name: 'Advanced', path: '/md-plugins/link/advanced' },
       ],
     },
+    {
+      name: 'Mermaid',
+      children: [
+        { name: 'Overview', path: '/md-plugins/mermaid/overview' },
+        { name: 'Advanced', path: '/md-plugins/mermaid/advanced' },
+      ],
+    },
     {
       name: 'Table',
       children: [

package/dist/templates/update/src/_q-press/components/MarkdownMermaid.vue

@@ -0,0 +1,123 @@
+<template>
+  <div class="markdown-mermaid q-my-md">
+    <div
+      v-if="errorMessage"
+      class="markdown-mermaid__error"
+      role="alert"
+    >
+      {{ errorMessage }}
+    </div>
+    <div
+      v-else-if="isRendering"
+      class="markdown-mermaid__loading"
+    >
+      Rendering diagram...
+    </div>
+    <div
+      ref="containerRef"
+      class="markdown-mermaid__diagram"
+    ></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { uid, useQuasar } from 'quasar'
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+
+const props = defineProps<{
+  code: string
+}>()
+
+const $q = useQuasar()
+const containerRef = ref<HTMLElement | null>(null)
+const errorMessage = ref('')
+const isRendering = ref(false)
+
+let disposed = false
+let renderRequest = 0
+
+async function renderDiagram(): Promise<void> {
+  if (import.meta.env.QUASAR_CLIENT !== true || containerRef.value === null) {
+    return
+  }
+
+  const requestId = ++renderRequest
+
+  errorMessage.value = ''
+  isRendering.value = true
+
+  await nextTick()
+
+  try {
+    const { default: mermaid } = await import('mermaid')
+
+    mermaid.initialize({
+      securityLevel: 'strict',
+      startOnLoad: false,
+      theme: $q.dark.isActive === true ? 'dark' : 'default',
+    })
+
+    const { svg, bindFunctions } = await mermaid.render(`markdown-mermaid-${uid()}`, props.code)
+
+    if (disposed === true || requestId !== renderRequest || containerRef.value === null) {
+      return
+    }
+
+    containerRef.value.innerHTML = svg
+    bindFunctions?.(containerRef.value)
+  } catch (error) {
+    if (disposed === false && requestId === renderRequest) {
+      errorMessage.value = error instanceof Error ? error.message : 'Unable to render diagram.'
+    }
+  } finally {
+    if (disposed === false && requestId === renderRequest) {
+      isRendering.value = false
+    }
+  }
+}
+
+onMounted(() => {
+  void renderDiagram()
+})
+
+watch(
+  () => [props.code, $q.dark.isActive] as const,
+  () => {
+    void renderDiagram()
+  },
+)
+
+onBeforeUnmount(() => {
+  disposed = true
+})
+</script>
+
+<style lang="scss">
+.markdown-mermaid {
+  border: 1px solid var(--q-separator-color);
+  border-radius: 8px;
+  overflow-x: auto;
+  padding: 1rem;
+
+  &__diagram {
+    min-width: 100%;
+    text-align: center;
+
+    svg {
+      max-width: 100%;
+      height: auto;
+    }
+  }
+
+  &__error {
+    color: var(--q-negative);
+    font-family: monospace;
+    white-space: pre-wrap;
+  }
+
+  &__loading {
+    color: var(--q-secondary);
+    font-style: italic;
+  }
+}
+</style>