md-viewer-py 1.0.8

Drop-in single-file Markdown viewer for any folder

md-viewer-py

Drop-in Markdown viewer for any folder — installable via pip.

Install once, use everywhere as mdview.

---

Install

pip install md-viewer-py

Or with uv:

uv tool install md-viewer-py

Or run without installing:

uvx --from md-viewer-py mdview

Or with pipx:

pipx install md-viewer-py

Then run from any directory:

mdview                        # serve current directory on port 8080
mdview 3000                   # custom port
mdview /path/to/docs          # custom directory
mdview /path/to/docs 3000     # both

Or run as a Python module without installing:

python -m md_viewer

Features

• Minimal dependencies — only watchdog for live reload, auto-installed with pip
• pip/pipx installable — install once, use anywhere as mdview
• Dashboard page — grid view of folders and files, macOS Finder-style
• Dark & light themes — polished UI with OS-aware theme toggle
• File tree sidebar — folder navigation with collapsible directories
• Full-text search — debounced search across all Markdown files with lazy loading
• Table of contents — auto-generated with scroll spy and collapsible groups
• Collapsible sections — click any heading to collapse/expand its content
• In-browser editing — toggle edit mode with toolbar, live preview, and save to disk
• Live reload — instant updates via SSE and native file system watching (watchdog)
• Syntax highlighting — code blocks highlighted with highlight.js
• Mermaid diagrams — flowcharts, sequence diagrams, and more rendered inline
• .gitignore support — respects ignore patterns from root and subdirectories
• Gzip compression — all responses compressed, ETag caching for the HTML page
• Keyboard shortcuts — arrow keys to navigate, / to search
• Reading progress bar — visual indicator of scroll position
• Mobile responsive — works on small screens with hamburger menu
• Print-friendly — clean print stylesheet for hard copies
• Custom port and directory — point it at any folder, pick any port

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
/ or Ctrl+K	Focus search
← ↑	Previous file
→ ↓	Next file

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

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