MrmoLabs/dsh-mermaid

dsh-mermaid

简体中文 | English

Render Mermaid fenced code blocks in DeepSeek Harness Web as SVG diagrams with a Code / Diagram toggle. The plugin supports streaming responses, dark mode, fullscreen viewing, zoom and pan, SVG export, and automatic fallback to source code when rendering fails.

Features

• Supports mermaid, mermaidjs, and mmd fenced code blocks
• Works with the DSH/Shiki plain fallback, where code elements may not have a language class
• Bundles the exact Mermaid 11.17.0 release and requires no runtime CDN
• Loads the bundled Mermaid runtime from DSH only after the first Mermaid block is detected
• Renders multiple diagrams through a serial queue and yields between renders to keep the page responsive
• Uses Mermaid's securityLevel: strict
• Suppresses Mermaid's built-in parse-error SVG so failed renders fall back cleanly without leaving temporary error graphics in the document
• Opens rendered diagrams in a fullscreen viewer with zoom, pan, reset, and fit-to-window controls
• Keeps keyboard focus inside the fullscreen viewer, isolates background content, and returns focus to the triggering control when closed
• Announces render and download status to assistive technologies and gives generated SVG diagrams accessible names
• Exports the rendered diagram as a standalone SVG file directly from the card
• Keeps fullscreen and SVG download actions available in both views and holds the toolbar in place while switching
• Localizes plugin-owned interface and status text in Simplified Chinese or English by following the page and browser language
• Enhances only `` blocks and ignores inline code
• Prevents stale asynchronous renders from overwriting newer streaming content
• Rejects individual diagrams over 50,000 characters or 2,000 lines before invoking Mermaid

Compatibility

Last verified with @deepseek-ai/dsh 0.1.2-rc.1 on 2026-09-05 using Node.js 22.23.2. DSH is currently a developer preview and may introduce compatibility-breaking changes; please open an issue if a newer DSH release changes its plugin loader or Markdown DOM.

Runtime and integration boundary

The Mermaid runtime runs in the DSH Web browser or Desktop renderer, where window and document are available. The Node.js host serves the bundled file over HTTP. The Node.js version requirement covers installation, builds, and the plugin host; this package does not currently provide a supported Node.js validation API.

lib/mermaid-runtime.js is an internal browser bundle. It is shipped for the plugin's same-origin runtime route and is not a public package export. Resolving dsh-mermaid/package.json and constructing a path to this file depends on internal packaging details that may change.

Integrators experimenting with server-side parsing must account for these requirements:

• Some diagram parsers sanitize labels through DOMPurify during parse(). Without a DOM, valid labeled flowcharts and state diagrams can throw addHook is not a function or sanitize is not a function. Successful parsing of one sequence diagram does not establish compatibility for other inputs.
• Provide a compatible DOM before the first runtime import, preferably in a dedicated worker or process. DOMPurify captures its environment during initialization; adding a DOM after import does not repair the cached module. Temporarily assigning globals around an asynchronous import can also expose them to other host code. Follow DOMPurify's server-side guidance when choosing a DOM implementation.
• On Windows, convert an absolute filesystem path with pathToFileURL(runtimePath).href before passing it to dynamic import().
• Distinguish invalid input from unavailable dependencies, environment failures, and timeouts. Mermaid's .hash error field is not a universal classifier: invalid pie syntax and unknown diagram types can also fail without it. An incomplete validation must not be reported as successful.
• Use the same Mermaid version and relevant configuration as the renderer. A successful parse() checks syntax; it does not guarantee successful layout or SVG rendering. Keep the renderer's error handling and source fallback.

Install

If dsh is available globally, install the stable npm release with:

dsh plugin --profile web add -w dsh-mermaid

Without a global dsh command, invoke DSH through npx:

npx.cmd --yes @deepseek-ai/dsh plugin --profile web add -w dsh-mermaid

DSH installs the package through pnpm, detects its dsh.bundle declaration, and automatically adds dsh-mermaid to the web profile bundle list. Restart DSH Web or refresh the page after installation.

Install the latest GitHub source

npx.cmd -y github:MrmoLabs/dsh-mermaid install

This runs the repository's dsh-mermaid installer, which asks DSH to install the GitHub source into the web profile. GitHub installation builds the package during installation. If pnpm reports that it blocked a build script, add the exact package key shown by pnpm to allowBuilds in the profile's pnpm-workspace.yaml, then run the command again. Prefer the npm release for normal use.

For DSH Desktop, add --profile desktop to the installer command. The installer displays its own help, errors, and completion messages in English or Simplified Chinese. It checks DSH_MERMAID_LANG, DSH_LANG, LC_ALL, LC_MESSAGES, LANG, and LANGUAGE in that order, then uses the system language. Neutral C/POSIX locale values are skipped. Set DSH_MERMAID_LANG=en or DSH_MERMAID_LANG=zh-CN to override the choice. This setting does not change messages printed by DSH or pnpm.

Update and uninstall

Update the npm release:

dsh plugin --profile web update -w dsh-mermaid

Uninstall:

dsh plugin --profile web remove -w dsh-mermaid

Restart DSH Web after updating or uninstalling.

Usage

Ask a model to output a Mermaid fenced code block:

flowchart LR A[Code] --> B[Diagram]

The code block receives Code / Diagram controls and opens in diagram view by default.

Develop from source

Node.js 22.19 or later is required.

npm.cmd install
npm.cmd run check
npm.cmd run build
dsh plugin --profile web add -w .

Build output is written to lib/. The lightweight client.js bootstrap is registered with the DSH client module loader as dsh-mermaid, while the bundled Mermaid runtime is served from the plugin's same-origin host route and loaded on demand. DSH resolves the relative installation path against the current plugin checkout.

npm.cmd run check builds the runtime and tests its real parser in separate processes, with and without a DOM, alongside the client tests. The DOM-backed parser tests use happy-dom as a test fixture and do not verify browser layout or SVG rendering, or recommend a production server-side DOM implementation.

For manual local development, the built package can also be copied to:

C:\Users\<username>\.dsh\profiles\web\node_modules\dsh-mermaid

Never commit the complete .dsh directory. It may contain conversations and credentials.

Release checks

npm.cmd run check
npm.cmd run build
npm.cmd pack --dry-run
git status --short
git diff --cached

License