mdserve

Fast markdown preview server with live reload and theme support.

Just run mdserve file.md and start writing. One statically-compiled executable that runs anywhere - no installation, no dependencies.

Features

• ⚡ Instant Live Reload - Real-time updates via WebSocket when markdown file changes
• 🎨 Multiple Themes - Built-in theme selector with 5 themes including Catppuccin variants
• 📝 GitHub Flavored Markdown - Full GFM support including tables, strikethrough, code blocks, and task lists
• 📊 Mermaid Diagrams - Automatic rendering of flowcharts, sequence diagrams, class diagrams, and more
• 🚀 Fast - Built with Rust and Axum for excellent performance and low memory usage

Installation

macOS (Homebrew)

# Add the tap
brew tap jfernandez/mdserve

# Install mdserve
brew install mdserve

Linux

curl -sSfL https://raw.githubusercontent.com/jfernandez/mdserve/main/install.sh | bash

This will automatically detect your platform and install the latest binary to your system.

Alternative Methods

Using Cargo

cargo install mdserve

From Source

git clone https://github.com/jfernandez/mdserve.git
cd mdserve
cargo install --path .

Manual Download

Download the appropriate binary for your platform from the latest release.

Usage

Basic Usage

# Serve a markdown file on default port (3000)
mdserve README.md

# Serve on custom port
mdserve README.md --port 8080
mdserve README.md -p 8080

Endpoints

Once running, the server provides (default: http://localhost:3000):

• / - Rendered HTML with live reload via WebSocket
• /raw - Raw markdown content (useful for debugging)
• /ws - WebSocket endpoint for real-time updates

Theme System

Built-in Theme Selector

• Click the 🎨 button in the top-right corner to open theme selector
• 5 Available Themes:
  • Light: Clean, bright theme optimized for readability
  • Dark: GitHub-inspired dark theme with comfortable contrast
  • Catppuccin Latte: Warm light theme with soothing pastels
  • Catppuccin Macchiato: Cozy mid-tone theme with rich colors
  • Catppuccin Mocha: Deep dark theme with vibrant accents
• Persistent Preference: Your theme choice is automatically saved in browser localStorage

Click the theme button (🎨) to access the built-in theme selector

mdserve running with the Catppuccin Macchiato theme - notice the warm, cozy colors and excellent readability

Development

Prerequisites

• Rust 1.70+ (2024 edition)
• Cargo

Building

cargo build --release

Running Tests

# Run all tests
cargo test

# Run integration tests only
cargo test --test integration_test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Axum web framework
• Markdown parsing by markdown-rs
• Catppuccin color themes
• Inspired by various markdown preview tools