mdv

Ultra-lightweight markdown-focused viewer.

Features

• CLI launch: mdv [path]
• Opens browser automatically by default
• File mode and folder mode
• Folder mode: markdown tree + preview pane
• GitHub-like markdown style (github-markdown-css)
• GFM task list rendering (- [ ], - [x])
• Mermaid diagram rendering from fenced blocks (click to expand fullscreen)
• Supports relative image/file links under opened root
• Secure path handling (prevents traversal outside root)

Split View

• Cmd+click (or right-click → "横に並べて開く") to open a file side-by-side
• Arrow Left / Right to switch panes, Arrow Up / Down to scroll active pane
• Exit multiview button to return to single pane

Document Index

• Floating table-of-contents popup showing h1–h3 headings
• Click a heading to smooth-scroll to it

Tree & Navigation

• Sidebar file tree with search/filter
• Collapsible sidebar toggle
• Auto-selects README.md as initial file
• Browser back/forward support via URL hash
• Relative markdown links navigate within the viewer
• Anchor links (#heading-id) smooth-scroll within a document
• External links open in a new tab

UI

• Scroll-to-top button on long documents
• Responsive mobile layout (< 900px)
• Dark code blocks with JetBrains Mono font
• Striped table rows

Security

• Content Security Policy (CSP) with nonce
• X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer
• Executable files (.html, .js, .svg, etc.) forced to download as attachment
• Symlink resolution to prevent directory breakout
• Mermaid is enabled and pulls transitive dependencies; risk assessment is documented in SECURITY.md

Install

npm install -g mdv-cli

After installing globally, mdv and mdv-ghostty are available in your shell.

Usage

# npx (no install required)
npx mdv-cli .
npx mdv-cli README.md

# after global install
mdv
mdv .
mdv README.md
mdv ./docs --port 5000 --host 127.0.0.1
mdv ./docs --no-open
mdv ./docs --open-mode none --print-url

Options

• --host <host>: bind host (default: 127.0.0.1)
• --port <number>: start port (default: 43110)
• --open-mode <browser|none>: browser launch mode (default: browser)
• --print-url: print a plain URL line after startup
• --no-open: do not auto-open browser
• --help: show help

Ghostty + mdv (macOS)

mdv-ghostty starts mdv, opens the preview in your default browser, and then arranges Ghostty + browser side by side.

mdv-ghostty .
mdv-ghostty ./docs

If you installed via npm install -g mdv-cli, mdv-ghostty is also available in your shell.

Ghostty config example

Use Ghostty split for shell workflow while browser stays on the other half:

keybind = cmd+d=new_split:right

Reference: https://ghostty.org/docs/config/keybind

Notes

• mdv-ghostty currently targets macOS (uses AppleScript).
• On first run, macOS may ask for Accessibility permission for terminal/osascript.
• If window arrangement fails, mdv still keeps running and prints the preview URL.
• --host 0.0.0.0 exposes file access over your network. Use only in trusted environments.

Scope / Constraints

• Target extensions: .md, .markdown
• Raw HTML in markdown is disabled (html: false)
• Mermaid is rendered client-side from ```mermaid blocks
• Mermaid security level is fixed to strict
• Excluded directories: .git, node_modules, vendor, vender, dist, build, out, .next, .cache
• If port is occupied, next available port is used automatically