README.md

May 23, 2026 · View on GitHub

md-viewer-py

Python versions License

Drop-in Markdown viewer for any folder

A local HTTP server that renders Markdown files in the browser with navigation, search, and editing. Install and run:

pip install md-viewer-py
mdview

▶ Click to watch the demo

Why mdview?

Point it at any folder and instantly browse your docs - no config files, no build step, no Node.js. It comes with sidebar navigation, global search, table of contents, dark mode, Mermaid diagrams, syntax highlighting, and an in-browser editor with live preview, all powered by Python's stdlib HTTP server and a single dependency (watchdog).

mdview vs. the alternatives

	mdview	MkDocs / Docusaurus	VS Code Preview	grip
Setup	`pip install`	Config + build + Node.js	Already installed	`pip install`
Multi-file navigation	✅	✅	❌	❌
Cross-file search	✅	✅	❌	❌
Live reload	✅	✅ (with plugin)	✅	❌
In-browser editing	✅	❌	✅	❌
Config required	None	✅	❌	API token
Works offline	✅	✅	✅	❌

Install

pip install md-viewer-py

Or with uv / pipx:

uv tool install md-viewer-py
pipx install md-viewer-py

Then run from any directory:

mdview                        # serve current directory on port 8080
mdview --port 3000            # custom port
mdview /path/to/docs          # custom directory
mdview /path/to/docs -p 3000  # both
mdview --help                 # show all options

All Features

Dashboard: grid view of folders and files, macOS Finder-style
Dark & light themes: auto-detects OS preference, manual toggle
File tree sidebar: collapsible directories with file name filter
Global search: search across all files from header with dropdown results
In-file search: Cmd/Ctrl+F to find and highlight matches
Table of contents: right panel with scroll spy and collapsible groups
In-browser editing: edit mode with live preview, save to disk
Live reload: instant updates when files change on disk
Syntax highlighting: for code blocks in all major languages
Mermaid diagrams: rendered inline with error feedback
LaTeX math: inline $...$ and block $$...$$ rendered with KaTeX
Audio playback: inline <audio> player for mp3, wav, ogg, m4a, aac, flac, opus
Keyboard shortcuts: full shortcut set with ? modal
Print-friendly: clean stylesheet with proper page breaks
Proper CLI: --help, --port, --host, --no-browser
Minimal dependencies: only watchdog, pip-installable

Keyboard Shortcuts

Key	Action
`⌘/Ctrl+F`	Find in current file
`⌘/Ctrl+Shift+F`	Search across all files
`Shift Shift`	Filter files by name
`/`	Focus search (legacy)
`?`	Show keyboard shortcuts
`← ↑`	Previous file
`→ ↓`	Next file
`Escape`	Close search / modal

Examples

Mermaid Diagrams: flowcharts, sequence diagrams, gantt charts, and more
LaTeX Math: inline and block equations via KaTeX
Audio Playback: inline audio player for common formats

How It Works

md-viewer-py is a pip-installable HTTP server built on Python's http.server. It scans the directory for .md files, serves a single-page UI with dark and light themes, and renders Markdown client-side using marked.js from a CDN. No build step, no config files. Just install and run.