bm-render-md

Render fenced Mermaid blocks from Markdown into beautiful, themeable SVGs (via beautiful-mermaid) and generate a rendered Markdown file that embeds (and links to) those SVGs.

• Source stays clean: keep your original ```mermaid blocks untouched by default
• Preview-friendly: the rendered Markdown uses clickable images so you can open/zoom diagrams easily
• Config-driven: put defaults in bm.config.json, override per run with flags

Requirements

• Node.js >= 18

Quickstart (recommended)

npx bm-render-md README.md

This will generate:

• SVG assets in .mermaid/
• README.rendered.md with embedded (clickable) images

Install options

Run once (no install)

npx bm-render-md path/to/file.md

Global install

npm i -g bm-render-md
bm-render-md path/to/file.md

Local development (this repo)

npm install
npm run render:md -- path/to/file.md

Configuration

Config cascade

Settings are merged in this order (later overrides earlier):

1. Global config — ~/.config/bm-render-md/config.json (or $XDG_CONFIG_HOME/bm-render-md/config.json)
2. Local config — ./bm.config.json in the current directory
3. CLI flags — --outDir, --outMd, --inPlace, --theme
4. --set overrides — highest priority

Global config (optional)

Create a global config that applies to all runs, regardless of directory:

If installed via npm (global):

mkdir -p ~/.config/bm-render-md
cp "$(npm root -g)/bm-render-md/bm.config.example.json" ~/.config/bm-render-md/config.json

If installed locally (npm install bm-render-md in your project):

mkdir -p ~/.config/bm-render-md
cp node_modules/bm-render-md/bm.config.example.json ~/.config/bm-render-md/config.json

If using this repo directly:

mkdir -p ~/.config/bm-render-md
cp bm.config.example.json ~/.config/bm-render-md/config.json

Or use a custom path via env var:

export BM_RENDER_MD_CONFIG=~/my-config/bm-render-md.json

Local config (bm.config.json)

Create a bm.config.json in your working directory. Copy from the bundled example:

cp node_modules/bm-render-md/bm.config.example.json bm.config.json

(Use $(npm root -g)/bm-render-md/ if you installed globally.)

By default, the CLI will load ./bm.config.json if present. You can also point to a specific config:

bm-render-md path/to/file.md --config bm.config.json

Precedence

1. Global config (if exists)
2. Local config (bm.config.json or --config)
3. CLI flags (--outDir, --outMd, --inPlace, --theme)
4. --set key=value overrides (highest)

Override render options quickly

bm-render-md path/to/file.md --set bg=#282a36 --set fg=#f8f8f2 --set padding=24

CLI options

• --config <file>: local JSON config file (default: ./bm.config.json if present; overrides global)
• --outDir <dir>: directory for generated SVGs (default: .mermaid)
• --outMd <file>: output Markdown path (default: <name>.rendered.md)
• --inPlace: write back into the input Markdown file instead of generating a derived Markdown file
• --theme <themeName>: apply a built-in beautiful-mermaid theme (merged into renderOptions)
• --set key=value: override a beautiful-mermaid render option (repeatable)

Config file schema (high level)

{
  "outDir": ".mermaid",
  "outMd": null,
  "inPlace": false,
  "theme": "dracula",
  "renderOptions": {
    "bg": "#282a36",
    "fg": "#f8f8f2",
    "padding": 40
  }
}

Everything under renderOptions maps 1:1 to beautiful-mermaid’s RenderOptions: bg, fg, line, accent, muted, surface, border, font, padding, nodeSpacing, layerSpacing, componentSpacing, transparent, interactive.

Output

• SVG assets: written to outDir (default .mermaid/)
• Rendered Markdown: written to <name>.rendered.md by default
• Zoom: diagrams are embedded as clickable images (click to open the SVG)

Examples

Example 1: Basic usage (default output)

Source file docs/flow.md:

# Process Flow

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Continue]
    B -->|No| D[Stop]
```

Command:

npx bm-render-md docs/flow.md

Result:

• docs/.mermaid/flow-01-<hash>.svg — generated SVG
• docs/flow.rendered.md — Markdown with embedded image links, e.g. [![...](.mermaid/flow-01-xxx.svg)](.mermaid/flow-01-xxx.svg)

Example 2: Custom output paths

npx bm-render-md docs/flow.md --outDir diagrams --outMd docs/flow.preview.md

Generates:

• docs/diagrams/flow-01-<hash>.svg
• docs/flow.preview.md

Example 3: Global config (Dracula everywhere)

~/.config/bm-render-md/config.json:

{
  "theme": "dracula",
  "outDir": ".mermaid",
  "renderOptions": { "padding": 40 }
}

Then from any directory:

npx bm-render-md docs/flow.md

All diagrams render with Dracula. Use BM_RENDER_MD_CONFIG to point to a different global file.

Example 4: Local Dracula theme (per-project)

bm.config.json in project root:

{
  "theme": "dracula",
  "outDir": ".mermaid",
  "renderOptions": { "padding": 40 }
}

Command:

npx bm-render-md docs/flow.md

Example 5: Inline theme override (no config file)

npx bm-render-md docs/flow.md --theme dracula --outDir .mermaid-dark

Example 6: Override specific colors

npx bm-render-md docs/flow.md --set bg=#0b1020 --set fg=#e5e7eb --set accent=#ff5555

Troubleshooting

If images not visible in Markdown preview

In VS Code / Cursor, use the built-in Markdown Preview: **Ctrl+Shift+V**.