Introduction

When developing agents using DSH (DeepSeek Harness), model responses often contain mermaid code blocks used to describe flows, architectures, or state transitions. The DSH web client defaults to treating them as ordinary code blocks: they have Shiki syntax highlighting and a Copy button, but the diagrams are invisible. To verify if the diagram is correct, you have to copy the source code to an external tool for rendering, switching back and forth which disrupts the debugging rhythm.

dsh-plugin-mermaid addresses this problem: it renders mermaid code blocks as charts within chat messages, while preserving the source code view, allowing you to switch back at any time. Below is an introduction to its features, principles, installation, and usage.

What is it

dsh-plugin-mermaid is a DeepSeek Harness (DSH) web client plugin maintained by lj970926 under the MIT license. It performs three main tasks:

  1. Render mermaid code blocks as charts in chat messages;
  2. Provide a “Source / Chart” toggle to switch between Mermaid source code and the rendered SVG;
  3. Automatically switch the Mermaid theme to follow the DSH dark/light theme; all blocks are re-rendered in real-time after theme changes.

Design trade-offs: Mermaid v11 loads from CDN on demand to avoid bundle bloat; the plugin has zero build steps, with a browser entry point as a hand-written CJS factory, meeting DSH client-modules service requirements; code block banners are natively integrated into the DSH interface, with buttons adjacent to the built-in Copy button, while the source view retains Shiki highlighting and copy functionality.

Core Features

  • Render mermaid code blocks as charts in chat messages;
  • “Source / Chart” toggle to switch between Mermaid source and rendered SVG anytime;
  • Automatically switch Mermaid theme following DSH dark/light theme;
  • Mermaid v11 loads from CDN on demand, without increasing bundle size;
  • Native DSH code block banner integration: buttons are next to the built-in Copy button, source view retains Shiki highlighting and copy;
  • Provide a “Re-render” button to force re-rendering after streaming output or CDN errors.

Implementation

The browser entry point for the plugin is lib/client.js. After loading, it does three things:

  1. Register itself via window.__ModuleLoader__.load({id, factory}) and inject styles;
  2. Identify mermaid blocks: read the .infostring text from the DSH banner, and use code[class*='language-mermaid'] as a forward-compatible fallback;
  3. Install MutationObserver to handle code blocks in streaming output, combined with a 500ms debounce to avoid frequent rendering triggers from streaming tokens.

Installation and Activation

Recommended installation directly from GitHub. This package publishes pre-built lib/ files and declares dsh.bundle, which can be directly loaded into the DSH web profile:

dsh plugin --profile web add github:lj970926/dsh-plugin-mermaid

After installation, you need to restart dsh web and force refresh the browser (Cmd+Shift+R).

If you need to pin a version for reproducibility, append the commit SHA or tag:

dsh plugin --profile web add github:lj970926/dsh-plugin-mermaid#<commit-or-tag>

For development and debugging, you can also install by checking out locally and linking the bundle:

dsh plugin --profile web add /absolute/path/to/dsh-plugin-mermaid

The repository also retains the legacy script install.sh, which directly copies files into an existing web profile:

git clone https://github.com/lj970926/dsh-plugin-mermaid.git
bash dsh-plugin-mermaid/install.sh

The script does two things: copies the folder to $DSH_HOME/profiles/web/node_modules/dsh-plugin-mermaid/ (default ~/.dsh/profiles/web/...), and appends an insert entry to $DSH_HOME/profiles/web/cordis.patch.yml (idempotent). After that, restart dsh web and force refresh the browser as well.

Two supplementary notes:

  • The published files are in lib/, the package has no prepare build step, and no pnpm allowBuilds authorization is needed; if you added build steps after forking, you need to add the package name to allowBuilds in the profile’s pnpm-workspace.yaml according to the DSH packaging documentation.
  • It is recommended to use dsh plugin add instead of manually editing the patch file: it records the bundle in the profile manifest, keeping it enabled even after profile updates. Also, newer versions of DSH require the profile’s cordis.patch.yml to be parseable as a top-level YAML array, defaulting to [] if no entries exist.

Typical Usage

After the above installation and restart steps, send any message containing a fenced mermaid block, for example:

```mermaid
flowchart LR
  A[Input] --> B[Process] --> C[Output]

DSH will first render it as a code block, and the plugin will then enhance this block:

1. Click the "Source / Chart" button to switch between Mermaid source and the rendered SVG;
2. After streaming output ends or if the diagram doesn't appear due to a CDN error, click "Re-render" to force a re-render;
3. After switching themes in Settings → Appearance, all blocks will re-render according to the matching Mermaid theme.

# Development and Customization

The browser-side files are pure JavaScript with no build steps. After modifying `lib/client.js`, you need to sync it back into the profile and restart `dsh web`:
```bash
bash install.sh

The DSH client-hmr plugin is disabled in the default web profile, so file changes won’t hot reload automatically. If you run DSH from source (pnpm run dev:web) and re-enable client-hmr, modifications to lib/client.js can be hot reloaded without restarting.

Another customizable point is the source for loading Mermaid. The first render requires access to cdn.jsdelivr.net; after that, the browser will cache Mermaid. For localization, simply change MERMAID_CDN in lib/client.js to a local URL.

Uninstallation

  1. Remove the corresponding block from ~/.dsh/profiles/web/cordis.patch.yml;
  2. Delete the directory: rm -rf ~/.dsh/profiles/web/node_modules/dsh-plugin-mermaid;
  3. Restart dsh web.

Use Cases and Notes

The plugin is suitable for all users viewing mermaid diagram responses in the DSH web client: architecture overview, process explanation, agent workflow debugging. You can view the diagrams directly in the conversation without switching to external tools.

Pre-use notes:

  • Requires DSH >= 0.1.0-rc.6 (tested on rc.6);
  • The first render requires network access to cdn.jsdelivr.net; for offline environments, localize it as described above first;
  • Like all DSH plugins, the plugin runs with the permissions of the current dsh process. It is recommended to read the source code and license (MIT) before installing to ensure it is correct.

Related Links

dsh-plugin-mermaid completes the “view diagrams directly” link in the DSH chat interface: zero build, on-demand loading, theme-following, ready to use once installed. The directory page and source code repository are as follows:

  • Directory Page: https://www.skillhub.cn/plugins/lj970926/dsh-plugin-mermaid
  • GitHub: https://github.com/lj970926/dsh-plugin-mermaid

(The community plugin directory is an independent site and has no official affiliation with DeepSeek / Hypothesis.)