viewmd

A command-line tool to view Markdown files in your browser with full GitHub-flavored markdown support, Mermaid diagram rendering, and live reload capabilities.

Features

• 📝 Full GitHub-flavored markdown support - Tables, task lists, strikethrough, etc.
• 📊 Mermaid diagram rendering - Flowcharts, sequence diagrams, and more
• 🎨 Syntax highlighting - Beautiful code blocks with automatic language detection
• 🎯 GitHub-style CSS - Authentic GitHub markdown rendering
• 🔄 Auto-reload on file changes - Enabled by default for instant feedback
• 📚 Multiple file support - View multiple files with table of contents
• 🚀 Auto-opens browser - Starts viewing immediately
• 🔒 Smart auto-shutdown - Server closes 1 second after browser tab closes
• 📄 Print-optimized - Clean page breaks for PDF generation

Installation

From Source

# Clone the repository
git clone https://github.com/peak6-labs/viewmd.git
cd viewmd

# Install dependencies
npm install

# Install globally (optional)
npm install -g .

Usage After Installation

# If installed globally
viewmd README.md

# Or run directly
./viewmd.js README.md

Usage

Basic Usage

# View a single file (auto-reload enabled by default)
viewmd README.md

# View multiple files
viewmd chapter1.md chapter2.md chapter3.md

# Snapshot mode (disable auto-reload)
viewmd --snapshot README.md

Command Line Options

Option	Short	Description
--port <number>	-p	Use specific port instead of random
--snapshot	-s	Render once without watching for changes
--no-open		Don't automatically open browser
--keep-alive	-k	Keep server running after browser closes
--help	-h	Display help information
--version	-V	Display version number

Features in Detail

Auto-Reload (Default)

By default, viewmd watches your markdown files and automatically reloads the browser when changes are saved. A brief "⟳ Reloaded" notification flashes when the page updates.

# Auto-reload is enabled by default
viewmd README.md

# Disable with snapshot mode
viewmd --snapshot README.md

Multiple File Support

View multiple markdown files in a single browser window with automatic table of contents generation:

# View multiple files
viewmd intro.md guide.md api.md

# Features for multiple files:
# - Automatic table of contents with navigation links
# - CSS page breaks between files for clean printing
# - File headers added for files without H1 headings

Mermaid Diagrams

Include Mermaid diagrams in your markdown for automatic rendering:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Try Again]
    D --> B
```

Server Behavior

• Auto-open: Browser opens automatically when server starts
• Smart shutdown: Server closes 1 second after browser tab closes
• Survives refresh: Server stays running during page refreshes
• Port selection: Uses random available port or specify with --port

Examples

Development Workflow

# Edit documentation with live preview
viewmd docs/*.md

# Review README before committing
viewmd README.md

# Generate PDF-ready view
viewmd --snapshot report.md

Specific Port

# Use a specific port
viewmd --port 3000 README.md

# Keep server running after browser closes
viewmd --keep-alive documentation.md

Advanced Usage

# View without opening browser (e.g., for remote access)
viewmd --no-open --port 8080 README.md

# Snapshot mode for CI/CD environments
viewmd --snapshot --no-open output.md

How It Works

1. File Processing: Reads markdown files and converts to HTML using marked.js
2. Server: Express server serves the rendered HTML with live reload capabilities
3. File Watching: Uses chokidar to detect file changes (when not in snapshot mode)
4. Browser Communication: Server-Sent Events (SSE) for real-time updates
5. Auto-shutdown: Tracks browser connections and closes when no clients remain

License

MIT