mddaemon

A local markdown server with Mermaid diagram validation.

https://github.com/user-attachments/assets/4461e224-38e1-40a1-8741-c1b8b80d97c2

Quick Start

npm install -g mddaemon
mddaemon run -p 8080 -t midnight-blue
mddaemon validate ~/docs/readme.md

Installation

npm install -g mddaemon

Usage

Start the daemon

mddaemon run -p 8080 -t midnight-blue              # Dark blue theme
mddaemon run -p 8080 -t sunny                      # Bright yellow theme
mddaemon run -p 8080 -t ember -d /path/to/docs     # Custom directory

Available themes:

• Dark: midnight-blue, ember
• Light: sunny, lavender, mint, sky, rose

Open a file in browser

mddaemon open ~/path/to/file.md

Validate Mermaid diagrams

mddaemon validate ~/path/to/file.md

Help

mddaemon --help
mddaemon --version
mddaemon run --help
mddaemon open --help
mddaemon validate --help

Configuration

Environment Variables

| Variable | Description | |----------|-------------| | MDDAEMON_PORT | Default port (used if --port not specified) | | MDDAEMON_THEME | Default theme (e.g., midnight-blue, sunny) |

Custom CSS

Add custom styles at ~/.config/mddaemon/style.css.

API

Server Info (HEAD /)

curl -I http://localhost:8080/

Returns headers:

• X-Mddaemon-Root: Server root directory
• X-Mddaemon-Port: Server port
• X-Mddaemon-Version: Version

Why

Mermaid diagrams in markdown are powerful but frustrating:

• No feedback loop - You write a diagram, commit it, and only discover syntax errors when viewing in GitHub/GitLab
• Cryptic errors - When errors do appear, they're rendered in the browser with no line numbers or block identification

This is especially painful when working with AI coding agents that generate Mermaid diagrams. The agent produces a diagram, you commit it, and later discover it doesn't render.

mddaemon provides a local daemon that validates diagrams before you commit, with precise error locations. Coding agents can run mddaemon validate to verify their diagrams are correct before finishing a task.

License

MIT