@md-plugins/md-plugin-mermaid 0.1.0-beta.20

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, MD-PLUGINS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @md-plugins/md-plugin-mermaid
+
+A **Markdown-It** plugin that renders Mermaid fenced code blocks. It is designed for Q-Press and Vue-based Markdown pages, while still allowing plain MarkdownIt users to render Mermaid-compatible `<pre>` blocks.
+
+## Features
+
+- Converts `mermaid` and `mmd` fenced code blocks into a configurable component.
+- Adds page import statements for Q-Press generated Vue pages.
+- Supports a plain `<pre class="mermaid">` render mode for custom MarkdownIt pipelines.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# with pnpm:
+pnpm add @md-plugins/md-plugin-mermaid
+# with bun:
+bun add @md-plugins/md-plugin-mermaid
+# with Yarn:
+yarn add @md-plugins/md-plugin-mermaid
+# with npm:
+npm install @md-plugins/md-plugin-mermaid
+```
+
+If you render Mermaid in the browser, install Mermaid in the consuming app:
+
+```bash
+pnpm add mermaid
+```
+
+## Usage
+
+### Q-Press or Vue Component Mode
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { mermaidPlugin } from '@md-plugins/md-plugin-mermaid'
+
+const md = new MarkdownIt()
+md.use(mermaidPlugin, {
+  componentName: 'MarkdownMermaid',
+})
+```
+
+### Raw MarkdownIt Mode
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { mermaidPlugin } from '@md-plugins/md-plugin-mermaid'
+
+const md = new MarkdownIt()
+md.use(mermaidPlugin, {
+  renderMode: 'pre',
+})
+```
+
+Then initialize Mermaid in your application after the HTML is mounted.
+
+## Markdown
+
+````markdown
+```mermaid
+graph TD
+  A[Write Markdown] --> B[Render Diagram]
+```
+````
+
+## Options
+
+| Option        | Type                 | Default                  | Description                                     |
+| ------------- | -------------------- | ------------------------ | ----------------------------------------------- |
+| languages     | string[]             | `['mermaid', 'mmd']`     | Fence languages treated as Mermaid diagrams.    |
+| renderMode    | 'component' \| 'pre' | `'component'`            | Output mode for Mermaid 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 component import | Page imports added to generated Vue components. |
+
+## Support
+
+If md-plugin-mermaid is useful in your workflow and you want to support ongoing maintenance:
+
+GitHub Sponsors: https://github.com/sponsors/hawkeye64
+PayPal: https://paypal.me/hawkeye64
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -0,0 +1,52 @@
+import { PluginWithOptions } from 'markdown-it';
+
+type MermaidRenderMode = 'component' | 'pre';
+interface MermaidPluginOptions {
+    /**
+     * Languages that should be treated as Mermaid diagrams.
+     *
+     * @default ['mermaid', 'mmd']
+     */
+    languages?: string[];
+    /**
+     * Render as a Vue component or as a plain Mermaid pre block.
+     *
+     * @default 'component'
+     */
+    renderMode?: MermaidRenderMode;
+    /**
+     * The Vue component used when renderMode is "component".
+     *
+     * @default 'MarkdownMermaid'
+     */
+    componentName?: string;
+    /**
+     * The prop name used to pass diagram source into the component.
+     *
+     * @default 'code'
+     */
+    codeProp?: string;
+    /**
+     * The class applied to plain pre blocks when renderMode is "pre".
+     *
+     * @default 'mermaid'
+     */
+    preClass?: string;
+    /**
+     * Page-level import statements required by the component render mode.
+     */
+    pageScripts?: string[];
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script import statements to include in generated Vue pages.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+declare const mermaidPlugin: PluginWithOptions<MermaidPluginOptions>;
+
+export { mermaidPlugin };
+export type { MermaidPluginOptions, MermaidRenderMode };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { PluginWithOptions } from 'markdown-it';
+
+type MermaidRenderMode = 'component' | 'pre';
+interface MermaidPluginOptions {
+    /**
+     * Languages that should be treated as Mermaid diagrams.
+     *
+     * @default ['mermaid', 'mmd']
+     */
+    languages?: string[];
+    /**
+     * Render as a Vue component or as a plain Mermaid pre block.
+     *
+     * @default 'component'
+     */
+    renderMode?: MermaidRenderMode;
+    /**
+     * The Vue component used when renderMode is "component".
+     *
+     * @default 'MarkdownMermaid'
+     */
+    componentName?: string;
+    /**
+     * The prop name used to pass diagram source into the component.
+     *
+     * @default 'code'
+     */
+    codeProp?: string;
+    /**
+     * The class applied to plain pre blocks when renderMode is "pre".
+     *
+     * @default 'mermaid'
+     */
+    preClass?: string;
+    /**
+     * Page-level import statements required by the component render mode.
+     */
+    pageScripts?: string[];
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script import statements to include in generated Vue pages.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+declare const mermaidPlugin: PluginWithOptions<MermaidPluginOptions>;
+
+export { mermaidPlugin };
+export type { MermaidPluginOptions, MermaidRenderMode };

package/dist/index.mjs

@@ -0,0 +1,54 @@
+import { resolvePluginOptions } from '@md-plugins/shared';
+
+const DEFAULT_MERMAID_PLUGIN_OPTIONS = {
+  languages: ["mermaid", "mmd"],
+  renderMode: "component",
+  componentName: "MarkdownMermaid",
+  codeProp: "code",
+  preClass: "mermaid",
+  pageScripts: ["import MarkdownMermaid from '@/.q-press/components/MarkdownMermaid.vue'"]
+};
+function getFenceLang(token) {
+  return token.info.trim().split(/\s+/, 1)[0] ?? "";
+}
+function getVueBinding(md, value) {
+  return md.utils.escapeHtml(JSON.stringify(value));
+}
+const mermaidPlugin = (md, options) => {
+  const resolvedOptions = resolvePluginOptions(
+    options,
+    "mermaidPlugin",
+    DEFAULT_MERMAID_PLUGIN_OPTIONS
+  );
+  const {
+    languages = DEFAULT_MERMAID_PLUGIN_OPTIONS.languages,
+    renderMode = DEFAULT_MERMAID_PLUGIN_OPTIONS.renderMode,
+    componentName = DEFAULT_MERMAID_PLUGIN_OPTIONS.componentName,
+    codeProp = DEFAULT_MERMAID_PLUGIN_OPTIONS.codeProp,
+    preClass = DEFAULT_MERMAID_PLUGIN_OPTIONS.preClass,
+    pageScripts = DEFAULT_MERMAID_PLUGIN_OPTIONS.pageScripts
+  } = resolvedOptions;
+  const mermaidLanguages = new Set(languages);
+  const originalFenceRender = md.renderer.rules.fence;
+  md.renderer.rules.fence = (tokens, idx, options2, env, self) => {
+    const token = tokens[idx];
+    if (!token) {
+      return "";
+    }
+    if (mermaidLanguages.has(getFenceLang(token)) === false) {
+      return originalFenceRender ? originalFenceRender(tokens, idx, options2, env, self) : self.renderToken(tokens, idx, options2);
+    }
+    if (renderMode === "pre") {
+      return `<pre class="${md.utils.escapeHtml(preClass)}"><code>${md.utils.escapeHtml(token.content)}</code></pre>`;
+    }
+    if (pageScripts.length > 0) {
+      env.pageScripts = env.pageScripts || /* @__PURE__ */ new Set();
+      for (const script of pageScripts) {
+        env.pageScripts.add(script);
+      }
+    }
+    return `<${componentName} :${codeProp}="${getVueBinding(md, token.content)}"></${componentName}>`;
+  };
+};
+
+export { mermaidPlugin };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@md-plugins/md-plugin-mermaid",
+  "version": "0.1.0-beta.20",
+  "description": "A markdown-it plugin for rendering Mermaid diagrams.",
+  "keywords": [
+    "markdown-it",
+    "mermaid",
+    "quasarframework",
+    "types",
+    "vue"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "files": [
+    "./dist"
+  ],
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@md-plugins/shared": "0.1.0-beta.20"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "markdown-it": "^14.2.0"
+  },
+  "peerDependencies": {
+    "markdown-it": "^14.2.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist/ node_modules/",
+    "test": "vitest"
+  }
+}