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!