Local Markdown previewer
npm install @hypersoweak/mdprevA clean, production-quality local Markdown previewer built with TypeScript and Node.js.
- 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.
``bash`
pnpm add -g @hypersoweak/mdprevor
npm install -g @hypersoweak/mdprevor run directly
npx @hypersoweak/mdprev [path]
Preview a specific file:
`bash`
mdprev README.md
Preview a directory (Sidebar enabled):
`bash`
mdprev ./docs
Preview current directory:
`bash`
mdprev
| 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
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).../../../../../etc/passwd
- Paths attempting to traverse outside () 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).
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.
The project follows a strict layered architecture:
- CLI (src/cli): Handles argument parsing and bootstraps the application.src/server
- Server (): Express application handling routing, static assets (/__fs__), and SSE events.src/renderer
- Renderer (): Pure markdown rendering logic (markdown-it, plugins, image rewriting). Independent of the server.src/core
- Core (): Utilities for file discovery, watching, and safe path resolution.src/ui
- UI (): HTML templating and CSS token generation. Framework-free.
`bash``
pnpm install
pnpm dev # Watch mode
pnpm build # Build to dist/
pnpm test # Run Vitest