███╗   ███╗ █████╗ ██████╗ ██╗  ██╗██████╗ ██████╗ ██╗   ██╗
 ████╗ ████║██╔══██╗██╔══██╗██║ ██╔╝██╔══██╗██╔══██╗╚██╗ ██╔╝
 ██╔████╔██║███████║██████╔╝█████╔╝ ██║  ██║██████╔╝ ╚████╔╝
 ██║╚██╔╝██║██╔══██║██╔══██╗██╔═██╗ ██║  ██║██╔═══╝   ╚██╔╝
 ██║ ╚═╝ ██║██║  ██║██║  ██║██║  ██╗██████╔╝██║        ██║
 ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝ ╚═╝        ╚═╝

markdpy - markdown in python

Python-based markdown preview server with live reload, themes, diagrams, and static export capabilities.

✨ Features

• 🔄 Live Reload: Automatic browser refresh on file changes with WebSocket
• 🎨 Multiple Themes: Light and dark themes with smooth toggle
• 📊 Mermaid Diagrams: Render flowcharts, sequence diagrams, and more
• 📐 MathJax Support: Beautiful mathematical formulas (KaTeX-ready)
• 📁 Directory Navigation: Browse multiple markdown files with sidebar
• 📤 Static Export: Generate self-contained HTML for sharing
• 🔒 Secure by Default: Directory traversal prevention, CSP headers
• ⚡ Fast: <100ms rendering, <200ms reload latency
• 🌐 Cross-Platform: Works on Linux, macOS, and Windows

📦 Installation

From PyPI (Recommended)

pip install markdpy

From Source

git clone https://github.com/eosho/markdpy.git
cd markdpy
pip install -e .

🚀 Quick Start

Serve a Single File

The simplest way to preview a markdown file:

markdpy README.md

This will:

• Start the server on http://127.0.0.1:8000
• Open your default browser automatically
• Enable live reload (changes refresh the browser)

Serve a Directory

Preview all markdown files in a directory with navigation:

markdpy docs/

Features:

• Sidebar navigation with all .md files
• Automatic index detection (index.md, README.md)
• Directory browsing support

Custom Configuration

markdpy docs/ --port 3000 --theme dark --no-open

📖 Detailed Usage

serve Command

Start a markdown preview server.

markdpy serve [PATH] [OPTIONS]

Arguments

Argument	Type	Default	Description
PATH	Path	. (current directory)	Path to markdown file or directory to serve

Options

Option	Short	Type	Default	Description
--port	-p	Integer	8000	Port to bind server (1024-65535)
--host	-h	String	127.0.0.1	Host address to bind server
--theme	-t	Choice	light	UI theme: light or dark
--no-open		Flag	False	Don't open browser automatically
--no-reload		Flag	False	Disable live reload (WebSocket)
--log-level		Choice	INFO	Logging level: DEBUG, INFO, WARNING, ERROR

Examples

Serve with custom port:

markdpy docs/ --port 3000

Dark theme without auto-opening:

markdpy README.md --theme dark --no-open

Debug mode with live reload disabled:

markdpy docs/ --log-level DEBUG --no-reload

Bind to all interfaces (accessible from network):

markdpy docs/ --host 0.0.0.0 --port 8080

export Command

Export markdown to static HTML files.

markdpy export SOURCE [OUTPUT] [OPTIONS]

Arguments

Argument	Type	Default	Description
SOURCE	Path	Required	Source markdown file or directory
OUTPUT	Path	output	Output directory for exported HTML

Options

Option	Short	Type	Default	Description
--theme	-t	Choice	light	Theme for exported HTML: light or dark
--minify		Flag	False	Minify exported HTML (reduces file size)

Examples

Export single file:

markdpy export README.md output/

Export directory with dark theme:

markdpy export docs/ site/ --theme dark

Export with minification:

markdpy export docs/ site/ --minify

📝 Supported markdown Features

GitHub Flavored markdown (GFM)

• Tables: Full table support with alignment
• Task Lists: - [ ] and - [x] checkboxes
• Strikethrough: ~~deleted text~~
• Autolinks: Automatic URL detection

Code Blocks

Syntax highlighting for 100+ languages using Pygments:

def hello_world():
    print("Hello from markdpy!")

Mermaid Diagrams

graph LR
    A[Start] --> B[Process]
    B --> C[End]

Loading

Supported diagram types:

• Flowcharts
• Sequence diagrams
• Class diagrams
• State diagrams
• Gantt charts
• Pie charts

Mathematical Expressions

Inline math: $E = mc^2$

Block math:

$$ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$

🔧 Configuration

Server Configuration

Configure via command-line options or environment variables:

Setting	CLI Option	Environment Variable	Default
Host	--host	HOST	127.0.0.1
Port	--port	PORT	8000
Theme	--theme	THEME	light
Log Level	--log-level	LOG_LEVEL	INFO

Themes are stored in browser localStorage:

• Key: markdpy-theme
• Values: light | dark

🧪 Development

Setup Development Environment

# Clone repository
git clone https://github.com/eosho/markdpy.git
cd markdpy

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/markdpy --cov-report=html

# Run specific test file
pytest tests/integration/test_http_view.py

# Run with verbose output
pytest -v

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

🐛 Troubleshooting

Port Already in Use

# Error: Port 8000 is already in use
markdpy README.md --port 8080

Live Reload Not Working

1. Check that --no-reload is not set
2. Verify WebSocket connection in browser console (F12)
3. Check firewall settings
4. Try --log-level DEBUG for detailed logs

Theme Not Loading

1. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
2. Check browser console for CSS loading errors
3. Verify src/markdpy/static/css/themes/ directory exists

Mermaid Diagrams Not Rendering

1. Ensure CDN is accessible (requires internet connection)
2. Check browser console for JavaScript errors
3. Verify diagram syntax at mermaid.live

---

Made with ❤️ by the markdpy team