md-viewer-py 1.2.1

Drop-in single-file Markdown viewer for any folder

md-viewer-py

Drop-in Markdown viewer for any folder

Install once, use everywhere as mdview.

A lightweight, pip-installable Markdown viewer that turns any folder into a browsable documentation site. Point it at a directory — it finds all .md files, renders them in a clean UI with syntax highlighting, diagrams, and live reload. No config, no build step, no Node.js. Just pip install md-viewer-py and mdview.

---

Install

pip install md-viewer-py

Or with uv:

uv tool 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

Or run as a Python module without installing:

python -m md_viewer

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 via SSE + watchdog
• Syntax highlighting: highlight.js for code blocks
• Mermaid diagrams: rendered inline with error feedback
• 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

Quick Start

pip install md-viewer-py
mdview

A browser tab opens automatically at http://localhost:8080.

Examples

• Mermaid Diagrams — flowcharts, sequence diagrams, gantt charts, and more

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

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 dark-themed UI, and renders Markdown client-side using marked.js from a CDN. No build step, no config files, no virtual environments beyond the install itself.

Alternative: Copy and Run

No install needed — just drop the wrapper into any folder:

python3 md-viewer.py

Blog

• How I Split 2,800 Lines Into 29 Files With Zero Regressions
• From Viewer to Workspace: Rebuilding md-viewer-py in 9 Days
• My Side Project Got Its First Security Vulnerability
• I Built a Zero-Dependency Markdown Viewer in Python

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines and the improvements & ideas list for open tasks.

Feel free to open an issue to discuss ideas before starting work.

License

MIT