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
<pre><code> 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:
```mermaid
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
MIT
