md-lv

md-lv

Serve Markdown files as HTML with live features

A lightweight local server that renders Markdown files as beautiful HTML pages, with support for GitHub Flavored Markdown, syntax highlighting, Mermaid diagrams, and MathJax formulas.

Features

• GitHub-style Markdown - Full GFM support with tables, task lists, and more
• Syntax Highlighting - Code blocks with automatic language detection
• Mermaid Diagrams - Flowcharts, sequence diagrams, and more
• MathJax Support - LaTeX math formulas ($...$ and $$...$$)
• Directory Browsing - Navigate through your files with ease
• Dark Mode - Automatic theme switching based on system preferences
• Search - Find files quickly with built-in search
• Keyboard Navigation - Navigate with vim-style keys (j/k)
• Security - Path traversal protection and security headers

Installation

npm install -g md-lv

Or use npx:

npx md-lv

Usage

Basic Usage

# Serve current directory
mdlv

# Serve specific directory
mdlv --dir /path/to/docs

# Serve on custom port
mdlv --port 8080

# Open README.md automatically
mdlv readme

CLI Options

Option	Short	Default	Description
--port	-p	3000	Server port
--host	-H	localhost	Bind address
--dir	-d	.	Document root
--no-watch		false	Disable file watching
--quiet	-q	false	Suppress output
--debug		false	Enable debug mode

Subcommands

mdlv readme

Find and display the nearest README.md file:

cd /path/to/project
mdlv readme

This command searches up the directory tree to find README.md and opens it in your browser.

Supported Content

Markdown Features

• Headings, paragraphs, lists
• Tables (GFM)
• Task lists
• Code blocks with syntax highlighting
• Blockquotes
• Links and images
• Horizontal rules

Mermaid Diagrams

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[OK]
    B -->|No| D[Cancel]
```

Math Formulas

Inline: $E = mc^2$

Block:

$$
\sum_{i=1}^n i = \frac{n(n+1)}{2}
$$

Keyboard Shortcuts

Shortcut	Action
Alt + ←	Go to parent directory
Alt + Home	Go to root
j / ↓	Next item (in directory listing)
k / ↑	Previous item
Enter	Open selected item
/	Focus search
Escape	Close search results

Requirements

• Node.js 18.0.0 or higher

Development

# Clone repository
git clone https://github.com/no-problem-dev/markdown-live-viewer.git
cd markdown-live-viewer

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm start

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Acknowledgments

• marked - Markdown parser
• highlight.js - Syntax highlighting
• Mermaid - Diagram rendering
• MathJax - Math formulas