Skip to main content

Mermaid Enhancement

Mermaid is a JavaScript-based diagramming tool that parses Markdown-like text syntax to create and dynamically modify diagrams.

1. Install the dependency​

npm install hexo-filter-mermaid-diagrams

2. Enable in the config​

mermaid:
  enable: true # enable Mermaid
  version: 10.9.3 # pin the version to avoid breakage from upstream "latest"
  url: # optional, full script URL (local path or any reachable CDN); empty = default CDN (npmmirror)
  options:
    startOnload: true

Custom script source​

By default Mermaid is loaded from npmmirror (theme.cdn or https://registry.npmmirror.com, Alibaba's China mirror). If your network cannot reach it (or you prefer another source), point mermaid.url to a reachable source:

# Local file (recommended: download mermaid.min.js into source/vendors/ — zero external dependencies)
mermaid:
  enable: true
  url: /vendors/mermaid.min.js
# Or a full URL of another CDN
mermaid:
  enable: true
  url: https://registry.npmmirror.com/mermaid/10.9.3/files/dist/mermaid.min.js

When the script source is unreachable, the theme shows a visible failure notice at the top of the post body (instead of waiting forever), keeping the raw text readable.

3. Draw diagrams in markdown​

Now you can draw diagrams in markdown posts (GitHub renders them automatically — use a mermaid code block):

graph LR
  A --> B
  A --> D

Previewing Mermaid locally​

To preview Mermaid rendering locally, you need a markdown compiler that supports Mermaid. For VS Code, install Markdown Preview Mermaid Support.

See the Mermaid guide for usage details.