mdp - Markdown Previewer

A fast CLI tool that previews Markdown files in your browser with GitHub-styled rendering.

---

Features

Feature	Description
GitHub Flavored Markdown	Tables, task lists, strikethrough, and autolinks
Syntax Highlighting	200+ languages via Chroma with GitHub-styled colors
Copy to Clipboard	Hover over code blocks to copy with one click
Dark Mode	Automatically follows system preference
Multi-file Support	Preview multiple files with sidebar navigation
Directory Support	Preview all .md files in a directory
Live Reload Server	Watch files and auto-refresh on changes
Respects .gitignore	Automatically skips ignored files
Mobile Responsive	Hamburger menu on smaller screens
Fuzzy Search	Quick file search with Cmd/Ctrl+K

---

Installation

Homebrew (macOS)

brew install sadiksaifi/tap/mdp

Curl (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/sadiksaifi/mdp/main/scripts/install.sh | sh

This installs mdp to ~/.local/bin and automatically configures your PATH.

From Source

git clone https://github.com/sadiksaifi/mdp.git
cd mdp
make install

Manual Build

make build
./mdp README.md

---

Upgrading

Homebrew

brew upgrade sadiksaifi/tap/mdp

Curl Installation

mdp upgrade

mdp automatically checks for updates and notifies you when a new version is available.

---

Usage

mdp <file.md>                    # Preview single file
mdp <file1.md> <file2.md>        # Preview multiple files with sidebar
mdp <directory>                  # Preview all .md files in directory
mdp -O output.html <file.md>     # Export to HTML file
mdp --serve <file.md>            # Start live reload server
mdp --serve --port 3000 <dir>    # Live reload on custom port

Options

Option	Description
-O, --output <file>	Write HTML to file instead of opening browser
--serve	Start live reload server instead of opening browser
--port <port>	Port for live reload server (default: 8080)
-h, --help	Show help message
-v, --version	Show version

Commands

Command	Description
upgrade	Upgrade mdp to the latest version
upgrade --force	Force upgrade even if already up to date

---

Examples

Single File

mdp README.md

Multiple Files

mdp README.md CHANGELOG.md docs/guide.md

Entire Directory

mdp ./docs/

Export to HTML

mdp -O docs.html README.md             # Export single file to HTML
mdp --output site.html ./docs/         # Export directory to single HTML file

Tip

Use --output to generate standalone HTML files for sharing or hosting documentation.

Live Reload Server

mdp --serve README.md              # Start server on port 8080
mdp --serve --port 3000 ./docs/    # Start server on port 3000

Tip

Use --serve when writing documentation to see changes in real-time without manually refreshing the browser.

---

Output

Mode	Output
Single file	Opens /tmp/mdpreview-{filename}.html in your default browser
Multiple files/directory	Opens /tmp/mdpreview-multi.html with sidebar navigation
Export mode (-O)	Writes HTML to specified file path
Live reload mode	Starts HTTP server at http://localhost:<port> with WebSocket auto-refresh

---

Keyboard Shortcuts

Note

These shortcuts work in multi-file mode.

Shortcut	Action
Cmd/Ctrl + K	Open fuzzy search palette
Cmd + B (Mac)	Toggle sidebar
Ctrl + B (Win/Linux)	Toggle sidebar
Escape	Close sidebar/search palette

Search Palette Navigation

Shortcut	Action
↑ / ↓	Navigate results
Ctrl + P / N	Navigate results (alternative)
Enter	Open selected file
Escape	Close palette

---

Development

Project Structure

cmd/mdp/              # CLI entry point
internal/
  converter/          # Markdown to HTML conversion
  template/           # HTML document generation (single & multi-file)
  filetree/           # File tree data structure for sidebar
  browser/            # Platform-specific browser opening
  server/             # Live reload HTTP server with WebSocket
assets/               # CSS assets

Commands

Command	Description
make build	Build the binary
make test	Run all tests
make coverage	Run tests with coverage
make install	Install to /usr/local/bin
make release	Build for all platforms
make clean	Remove build artifacts

Releases

Releases are managed by Tagsmith using the repo's .tagsmith.jsonc config.

npx tagsmith@latest targets
npx tagsmith@latest tag --channel stable --bump patch --dry-run --json
npx tagsmith@latest tag --channel stable --bump patch --push

Tagsmith-created annotated v* tags are validated in CI before release artifacts and the Homebrew tap update are published.

Running Tests

make test

Important

Always run tests before submitting a pull request.

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

MIT