Introduction¶

When chatting with a model in DSH Web, the assistant often outputs ```mermaid code fences—flowcharts, sequence diagrams, class diagrams, etc.—in its replies. By default, these fences are just plain text code blocks, requiring you to copy them to an external tool to view the diagram.

If you want to see the diagrams directly in the session messages without stuffing the Mermaid runtime into the frontend startup bundle and slowing down the initial load, you need a plugin that loads on demand and only works when a fence appears. Below, we introduce the community plugin dsh-mermaid (maintainer AKS1st), which renders Mermaid fences in DSH Web sessions into SVGs on the fly, with optimizations for long conversations including viewport-driven rendering and an asynchronous queue.

What It Is¶

dsh-mermaid is a DSH client plugin (current version 0.5.0, MIT license). After installing it into the web profile, it monitors the session DOM and renders code fences with an infostring of mermaid into SVG diagrams while preserving the language banner and copy button (copying still copies the source code).

The plugin is listed on the SkillHub Community Directory under the client category; its source is hosted on GitHub: AKS1st/dsh-mermaid.

How It Works¶

The plugin is divided into a Host half and a Client half, each with clear responsibilities.

Host half (src/index.ts) registers a webServer prefix route /mermaid-dist, lazily serves the UMD build from its own node_modules/mermaid, and provides a fixed config.json endpoint.

Client half (src/client/) performs the actual rendering on the browser side with the following main behaviors:

1. Only processes finalized fences—does not render during streaming; waits until the assistant’s reply is complete before acting.
2. Lazily loads the mermaid library only upon encountering the first Mermaid fence (cached once by the browser).
3. Viewport-driven rendering: Rendering starts only when a fence enters the viewport (with a 300px preloading margin); rendering stops when the diagram leaves the viewport and resumes when it re-enters.
4. Asynchronous queue rendering: For multiple diagrams, renders them one by one, yielding the main thread between renders. During the initial render, a loading animation is displayed and replaced with the SVG upon completion.
5. securityLevel is always strict; tags are sanitized by mermaid’s built-in DOMPurify, and click handling is never bound.
6. With theme: auto, diagram colors follow the GUI light/dark theme, and existing diagrams in the viewport are automatically re-rendered when the attribute flips.
7. The zoom button on the code block banner opens a fullscreen overlay with support for scroll-wheel zooming, left/middle-click drag panning, and closing via background click or Esc.
8. On render failure, the source code block is preserved, an error summary is displayed below the diagram frame, and a one-click option to copy the error or send it to AI for fixing is provided.

The client bundle is approximately 10 KB (gzip ~4 KB); mermaid (~700 KB) is loaded on demand only when a mermaid fence actually appears, not in the boot image.

Installation and Activation¶

Install from the GitHub repository; the build runs automatically in the prepare script:

dsh plugin --profile web add github:AKS1st/dsh-mermaid
dsh web   # Restart the web service to apply the profile

If pnpm prompts that git dependencies require running build scripts (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED), follow the instructions to add the package to the allowBuilds section in the profile’s pnpm-workspace.yaml and retry.

For local development, build first then install:

npm install
npm run build
dsh plugin --profile web add .
dsh web

To uninstall:

dsh plugin --profile web remove dsh-mermaid

Configuration¶

The combined package injects the following configuration by default via cordis.patch.yml:

- insert:
    - id: mermaid
      name: 'dsh-mermaid'
      config:
        theme: auto
        maxTextSize: 50000
        maxEdges: 2000
        securityLevel: strict

Override with - set: or - update: in the profile’s cordis.patch.yml.

Typical Usage¶

After installing and restarting the web service, no additional steps are required. When the assistant outputs a Mermaid fence in a session message, the plugin automatically takes over rendering. For example, if the assistant replies with:

```mermaid
flowchart LR
  A[User Question] --> B[DSH Web]
  B --> C[dsh-mermaid]
  C --> D[SVG Diagram]
```

Once the fence is finalized and enters the viewport, the code will be rendered as an SVG flowchart. You can click the zoom button on the code block banner to view it in a fullscreen overlay, using the scroll wheel to zoom and dragging to pan; you can also copy the source code directly or send rendering errors to AI for fixing with one click.

Security Model and Known Limitations¶

Security Model:

• Assistant output is untrusted: securityLevel is locked to strict, and HTML within tags is sanitized by mermaid’s internal DOMPurify; bindFunctions is not called, keeping click handling lazy.
• On render failure, the original plain text code block is preserved (no erroneous HTML is ever rendered), and an error summary is displayed below the diagram frame; the full error is also output to the console.

Known Limitations:

• Relies on stable hooks from the main frontend’s CodeBlock (literal class md-code-block and infostring text); selectors must be updated synchronously if the upstream renderer is refactored.
• Does not render during streaming; renders only after finalization.
• Click interactions within mermaid are unavailable with securityLevel: strict.

Applicable Scenarios and Notes¶

Who It’s For:

• Those who frequently have the model draw flowcharts, architecture diagrams, or sequence diagrams in DSH Web sessions and want to view them directly without switching tools repeatedly;
• Those concerned about initial page performance, wanting the Mermaid runtime to load on demand without polluting the boot image;
• Scenarios requiring automatic light/dark theme following and viewport-driven rendering for long conversations.

Pre-installation Notes:

DSH’s philosophy is “everything is a plugin.” The community directory SkillHub is an independent site, not officially affiliated with DeepSeek or HuanFang. Plugins run with the current dsh process permissions; before installing, you should check the source code and MIT license to confirm it meets your security requirements. The plugin requires Node.js ^22.19 || >=24.

Links¶

• Community Directory: https://www.skillhub.cn/plugins/AKS1st/dsh-mermaid
• GitHub Repository: https://github.com/AKS1st/dsh-mermaid