npm package: @hypersoweak/mdprev
Description: Local Markdown previewer
Latest version: 0.1.1

# 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

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

### Commands

Preview a specific file:

```bash
mdprev README.md
```

Preview a directory (Sidebar enabled):

```bash
mdprev ./docs
```

Preview current directory:

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

```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**.
   - `![](./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

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