mermaidmd-launchpad

CLI markdown viewer with built-in Mermaid rendering.

Features

• view command to generate/open viewer HTML directly (no local server required).
• view --terminal mode to open the generated HTML inside a terminal browser engine.
• serve command to preview markdown as rendered HTML over local HTTP.
• build command to generate standalone HTML.
• Mermaid code fences are rendered automatically.
• Mermaid JavaScript is loaded from local assets/mermaid.min.js (no CDN requirement).
• Parallel subtask watcher + journal generation scripts.

Setup

bash scripts/setup-mermaid-asset.sh

Usage

# Start terminal viewer (serves markdown + opens carbonyl with low-ghosting flags)
npm start

# Start browser viewer (serves markdown + opens desktop browser if available)
npm run start:browser

# View markdown by generating a viewer file in /tmp
node src/cli.js view README.md --open

# View markdown directly in terminal browser (requires carbonyl or browsh)
node src/cli.js view README.md --terminal

# Use a specific terminal browser command
node src/cli.js view README.md --terminal --terminal-browser browsh

# Serve markdown on localhost
node src/cli.js serve README.md --port 4173

# Build static HTML from markdown
node src/cli.js build README.md -o README.html

Or use the installed binary:

mdv view README.md --open
mdv view README.md --terminal
mdv build README.md -o README.html

In restricted sandboxes where sockets are blocked, use view instead of serve. For view --terminal, install carbonyl or browsh, or set MDV_TERMINAL_BROWSER.

Shell Aliases

Install aliases/functions into your shell rc:

bash scripts/install-aliases.sh
source ~/.zshrc

Alias usage:

mdvb MERMAID_COMPLEX_TEST.md   # open in browser mode
mdvt MERMAID_COMPLEX_TEST.md   # open in terminal mode
mdb README.md                  # short alias for mdvb
mdt README.md                  # short alias for mdvt

Startup Script

scripts/start-terminal.sh launches mdv serve with terminal-optimized rendering and then opens Carbonyl.

# Default file (README.md)
bash scripts/start-terminal.sh

# Custom markdown file
bash scripts/start-terminal.sh docs/guide.md

Overrides

Use these environment variables to override startup behavior.

Variable	Default	Used by	Purpose
MDV_BROWSER_HOST	0.0.0.0	scripts/start-browser.sh, mdvb	Bind host for browser serve mode
MDV_BROWSER_PORT	4173	scripts/start-browser.sh, mdvb	Bind port for browser serve mode
MDV_BROWSER_OPEN	1	scripts/start-browser.sh, mdvb	Auto-open desktop browser (1=on, 0=off)
MDV_HOST	127.0.0.1	scripts/start-terminal.sh, mdvt	Bind host for terminal serve mode
MDV_PORT	4173	scripts/start-terminal.sh, mdvt	Bind port for terminal serve mode
MDV_TERMINAL_BROWSER	carbonyl	scripts/start-terminal.sh, mdvt	Terminal browser command
MDV_TERMINAL_FPS	30	scripts/start-terminal.sh, mdvt	Carbonyl max FPS
MDV_TERMINAL_ZOOM	100	scripts/start-terminal.sh, mdvt	Carbonyl zoom percent
MDV_CARBONYL_FLAGS	--disable-gpu --disable-gpu-compositing --disable-smooth-scrolling --disable-lcd-text	scripts/start-terminal.sh, mdvt	Extra Chromium/Carbonyl flags
MDV_RC_FILE	auto-detected (~/.zshrc or ~/.bashrc)	scripts/install-aliases.sh	Target rc file for alias install

Examples:

# Browser mode via alias, custom port
MDV_BROWSER_PORT=4300 mdvb MERMAID_COMPLEX_TEST.md

# Browser mode without auto-open
MDV_BROWSER_OPEN=0 mdvb README.md

# Terminal mode via alias, tuned rendering
MDV_TERMINAL_FPS=24 MDV_TERMINAL_ZOOM=90 mdvt MERMAID_COMPLEX_TEST.md

# Override Chromium flags passed to Carbonyl
MDV_CARBONYL_FLAGS="--disable-gpu --disable-gpu-compositing --disable-smooth-scrolling --disable-lcd-text" \
  mdvt README.md

Mermaid Example

flowchart TD
  User[User Markdown] --> CLI[mdv CLI]
  CLI --> HTML[Rendered HTML]
  HTML --> Browser[Browser or Carbonyl]

Loading

End-to-End Validation

bash scripts/test-e2e.sh

Parallel Subtask Watcher + Journal

scripts/run-with-journal.sh starts a watcher process in parallel, runs environment checks + e2e validation, and writes TASK_JOURNAL.md.

bash scripts/run-with-journal.sh