mdv

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 -p 8080          # pin the 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.

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
  -follow-symlinks    follow symlinked directories
  -sort alpha|mtime   sidebar sort order (default alpha, dirs first)
  -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.