Markdown Server

A simple CLI tool that serves markdown files as HTML with beautiful Tailwind CSS styling and automatic dark/light theme support.

~~This project was vibe coded with AI pair programming!~~ Seemingly you only vibe code if you don't review anything and let the agents do all the work. So this is probably less vibe coded and I am just too lazy to write these simple things manually anymore. But there might still be AI slop lingering as I use this script, but it's low to non-existent stakes.

Features

• 🚀 Fast & Lightweight: Built with Express.js
• 🎨 Beautiful Styling: Uses Tailwind CSS with typography plugin
• 🌙 Dark/Light Mode: Automatic theme switching based on system preferences
• 📁 Directory Listing: Automatically lists all markdown files in the directory
• 🔗 Smart URLs: Access files with or without the .md extension
• 📱 Responsive: Works great on desktop and mobile devices
• 💻 Syntax Highlighting: Code blocks with Prism.js (light/twilight themes)
• 🎯 Minimal UI: Clean, distraction-free reading experience

Installation

Option 1: Homebrew (Recommended)

# Add the tap
brew tap pders01/md

# Install the CLI
brew install md-server

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/pders01/md.git
cd md

# Install dependencies
pnpm install

# Build the CLI
pnpm run build

Option 3: Global Symlink (Development)

For easy development and testing, you can create a global symlink:

# From the project directory
pnpm link

# Now you can run from anywhere
md-server --port 3000

Or use the provided install script:

# Run the install script (requires sudo)
./scripts/install.sh

Or create a manual symlink:

# Create a symlink to the built CLI
ln -s "$(pwd)/dist/index.js" /usr/local/bin/md-server

# Make it executable
chmod +x /usr/local/bin/md-server

# Now you can run from anywhere
md-server --port 3000

To uninstall, run: sudo rm /usr/local/bin/md-server or use ./scripts/uninstall.sh

Usage

Running the Server

# Start with default settings (port 3000, current directory)
md-server

# Custom port and directory
md-server --port 8080 --directory ./docs

Command Line Options

• -p, --port <port>: Port to run the server on (default: 3000)
• -d, --directory <dir>: Directory to serve markdown files from (default: current directory)
• -h, --host <host>: Host to bind the server to (default: localhost)

Examples

Basic Usage

# Serve markdown files from current directory
md-server

# Serve from a specific directory
md-server --directory ./my-docs

# Use a different port
md-server --port 8080

File Access

Once the server is running, you can access your markdown files at:

• http://localhost:3000/ - Directory listing
• http://localhost:3000/README.md - View README.md
• http://localhost:3000/README - Same as above (extension optional)

Markdown Features

The server supports all standard markdown features with enhanced styling:

Headers

H1 Header

H2 Header

H3 Header

Lists

• Unordered list item 1
• Unordered list item 2
  • Nested item
  • Another nested item

1. Ordered list item 1
2. Ordered list item 2
3. Ordered list item 3

Code

Inline code: console.log('Hello, World!')

// Code block with syntax highlighting
function greet(name) {
  return `Hello, ${name}!`;
}

Links and Images

Visit GitHub

Tables

| Feature | Description | Status | |---------|-------------|--------| | Markdown Support | Full markdown parsing | ✅ | | Tailwind Styling | Beautiful, responsive design | ✅ | | Dark/Light Mode | Automatic theme switching | ✅ | | Syntax Highlighting | Prism.js with light/twilight themes | ✅ | | Directory Listing | Auto-generated file index | ✅ | | CLI Interface | Easy command-line usage | ✅ |

Blockquotes

This is a blockquote. It can contain multiple lines and is styled with a left border.

Development

Project Structure

md/
├── cli.js              # CLI entry point
├── src/
│   ├── server.js       # Express server logic
│   └── styles/
│       └── tailwind.css # Tailwind source styles
├── public/
│   ├── styles.css      # Custom styles
│   ├── template.html   # HTML template
│   ├── tailwind.css    # Built Tailwind CSS
│   ├── prism.js        # Syntax highlighting
│   ├── prism-light.css # Light theme
│   └── prism-dark.css  # Dark theme (twilight)
├── tailwind.config.js  # Tailwind configuration
├── vite.config.js      # Vite configuration
└── package.json        # Dependencies and scripts

Development Commands

# Build CSS
pnpm run build:css

# Watch for CSS changes
pnpm run watch

# Start development server
pnpm run dev

Dependencies

• express: Web server framework
• marked: Markdown parser
• commander: CLI argument parsing
• chalk: Terminal color output
• prismjs: Syntax highlighting
• tailwindcss: Styling framework
• @tailwindcss/typography: Typography plugin
• vite: Bundler for development and production

Documentation

For more detailed information, see:

• Developer Guide - Development setup, project structure, and contribution guidelines
• Markdown Features - Complete demonstration of all supported markdown features

Homebrew Tap

You can install md-server directly from the official Homebrew tap:

brew tap pders01/md
brew install md-server

License

MIT License - feel free to use this project for your own needs!