mdv

A tiny local Markdown browser. Point it at a directory and it serves an HTML view of every .md / .markdown file under it, with a GitHub-style expandable sidebar and GFM + syntax-highlighted code + math + Mermaid rendering.

Built for quickly browsing the piles of Markdown files coding agents drop into project trees.

Install

go install github.com/ian-ross/mdv@latest

Use

mdv                  # serve CWD
mdv ./docs           # serve a specific subtree
mdv host:/srv/docs   # serve a remote subtree over SSH
mdv -p 8080          # pin the local/browser port
mdv --sort=mtime     # newest file first (good for agent dumps)

mdv binds to 127.0.0.1, picks port 7999 (or an OS-assigned free port if 7999 is taken), and opens your browser. Ctrl-C to stop.

Remote targets use your system ssh command, so SSH config aliases, ProxyJump, ControlMaster, and agent-based auth work as usual. Passwordless SSH must already be configured, and mdv must be installed in PATH on the remote host. The remote server binds to 127.0.0.1 on the remote host and is exposed locally through an SSH tunnel.

What it indexes

• .md and .markdown files.
• Skips hidden directories (.git, .venv, …) by default.
• Honors a root-level .gitignore when present.
• Falls back to a built-in skip list (node_modules, target, dist, build, vendor, __pycache__) when there is no .gitignore.
• Pass --no-ignore to include everything.
• Pass --follow-symlinks to follow symlinked directories (with cycle detection).

Flags

  -host string        host/address to bind (default "127.0.0.1")
  -p / -port int      port to bind (default 7999; 0 for OS-assigned)
  -no-open            don't auto-open a browser
  -quiet              suppress access log
  -no-ignore          include files a .gitignore would hide
  -include path       force-include a path even if ignored (repeatable)
  -follow-symlinks    follow symlinked directories
  -sort alpha|mtime   sidebar sort order (default alpha, dirs first)
  -remote-port int    remote mdv server port for SSH mode (default 7999)
  -v / -version       print version and exit

What it renders

• GFM (tables, task lists, strikethrough, autolinks)
• Syntax-highlighted code blocks (Chroma, github / github-dark)
• Heading anchors
• Raw HTML passthrough
• Footnotes
• YAML front matter is stripped
• Math via KaTeX ($...$, $$...$$, \(...\), \[...\])
• Mermaid diagrams via ```mermaid blocks
• Relative .md links rewritten to in-app URLs (anchor fragments preserved)
• Relative non-Markdown links served as raw assets
• External links open in a new tab
• Broken relative links styled distinctly

KaTeX and Mermaid are loaded from jsdelivr on demand (only on pages that need them), so an internet connection is needed to render those specific pages.

Styling

Light and dark themes switch automatically via prefers-color-scheme.

License

MIT — see LICENSE.