Markdown Viewer

A lightweight development server for viewing Markdown files with hot reload functionality.

Features

• 🚀 Quick start with npx @bloom-and-co/mdviewer
• 📝 GitHub Flavored Markdown (GFM) support
• 🎨 Syntax highlighting for code blocks
• 📊 Mermaid diagram support
• 🔄 Hot reload on file changes (automatic browser refresh)
• 🔒 Security features (path traversal protection, hidden file protection)
• ⚡ Fast and lightweight

Requirements

• Node.js 20.0.0 or higher
• macOS users: fsevents package for optimal file watching performance
  • Automatically installed as an optional dependency
  • Hot Reload will be disabled if not available (polling is not used for performance reasons)

Installation

npm install -g @bloom-and-co/mdviewer

Or use directly with npx:

npx @bloom-and-co/mdviewer

Usage

Start the server in the current directory:

mdviewer

Start the server in a specific directory:

mdviewer /path/to/docs

Specify a custom port:

PORT=8080 mdviewer

Development

Setup

npm install

Build

npm run build

Test

npm test

Watch mode

npm run dev

Project Structure

mdviewer/
├── src/              # TypeScript source files
├── tests/            # Test files
├── dist/             # Compiled JavaScript (generated)
├── package.json      # Project configuration
├── tsconfig.json     # TypeScript configuration
└── jest.config.js    # Jest configuration

Technology Stack

• Runtime: Node.js 20+
• Language: TypeScript 5+ (strict mode)
• Markdown Parser: marked v11+ with marked-gfm
• Syntax Highlighting: Prism.js v1.29+
• File Watching: chokidar v4+ (native file events, no polling)
• Testing: Jest v29+

Hot Reload

Hot Reload automatically refreshes your browser when files change. A green indicator in the top-right corner shows the connection status:

• Green "Hot Reload": Connected and watching for changes
• Yellow "Reconnecting...": Attempting to reconnect
• Red "Disconnected": Connection lost (max retries exceeded)

Platform Support

• macOS: Requires fsevents for native file system events
• Linux: Uses inotify (built into kernel)
• Windows: Uses ReadDirectoryChangesW (built into OS)

File Event Detection

Hot Reload monitors:

• ✅ File creation (new files)
• ✅ File modification (content changes)
• ✅ File deletion (may be unreliable in some environments)

Hidden files (starting with .) are automatically ignored.

Troubleshooting

If Hot Reload is not working:

1. macOS users: Ensure fsevents is installed

   npm install fsevents

2. Check the indicator: If you don't see the green indicator, Hot Reload is disabled

3. File system limitations: Some environments (Docker, network drives) may have limited file event support

License

MIT