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

$3

``bash
pnpm add -g @hypersoweak/mdprev


or

npm install -g @hypersoweak/mdprev

or run directly

npx @hypersoweak/mdprev [path]
`

$3

Preview a specific file:

`bash
mdprev README.md
`

Preview a directory (Sidebar enabled):

`bash
mdprev ./docs
`

Preview current directory:

`bash
mdprev
`

$3

| 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:

`bash
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.
-  inside docs/intro.md resolves to docs/img.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

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