mdprev

A clean, production-quality local Markdown previewer built with TypeScript and Node.js.

Features

• Live Reload: Automatically updates when markdown files change (using SSE).
• GitHub-like Styling: Includes Dark (default) and Light themes with optimized typography and tables.
• Math Support: Renders $inline$ and $$block$$ math using KaTeX.
• Syntax Highlighting: Code blocks highlighted with highlight.js.
• Sidebar Navigation: Browse all markdown files in folder mode, with collapsible sidebar.
• Secure Image Resolution: Safely resolves relative image paths while preventing directory traversal.

Usage

Installation

pnpm add -g @hypersoweak/mdprev
# or
npm install -g @hypersoweak/mdprev
# or run directly
npx @hypersoweak/mdprev [path]

Commands

Preview a specific file:

mdprev README.md

Preview a directory (Sidebar enabled):

mdprev ./docs

Preview current directory:

mdprev

Options

| Option | Description | Default | | ----------- | --------------------------------- | -------------------------------- | | --version | Show version information | - | | --theme | dark or light | dark | | --port | Port to listen on | 5173 (auto-increments if busy) | | --no-open | Do not open browser automatically | false |

Example:

mdprev docs --theme light --port 3000

Image Resolution Rules

Images are resolved to ensure they work locally exactly as they would when hosted, with strict security checks.

1. Relative Paths: Resolved relative to the current markdown file.

   • ![](./img.png) inside docs/intro.md resolves to docs/img.png.
   • ![](../assets/logo.png) inside docs/sub/page.md resolves to docs/assets/logo.png.

2. Root Confinement:

   • All resolved paths must remain within the project root (the directory you opened mdprev in, or the file's directory).
   • Paths attempting to traverse outside (../../../../../etc/passwd) are blocked and not rewritten.

3. External URLs: http://, https://, and data: URIs are left unchanged.

4. Absolute Paths: Paths starting with / are left unchanged (assumed to be absolute server paths or external).

Theme Behavior

The theme is controlled via the --theme flag.

• Dark Mode: Uses GitHub Dark Dimmed color palette.
• Light Mode: Uses GitHub Light color palette.
• No Auto-detection: The theme is explicit to ensure consistent rendering regardless of system preference, defaulting to Dark.

Architecture

The project follows a strict layered architecture:

• CLI (src/cli): Handles argument parsing and bootstraps the application.
• Server (src/server): Express application handling routing, static assets (/__fs__), and SSE events.
• Renderer (src/renderer): Pure markdown rendering logic (markdown-it, plugins, image rewriting). Independent of the server.
• Core (src/core): Utilities for file discovery, watching, and safe path resolution.
• UI (src/ui): HTML templating and CSS token generation. Framework-free.

Development

pnpm install
pnpm dev       # Watch mode
pnpm build     # Build to dist/
pnpm test      # Run Vitest