Background HTTP server rendering markdown files with calm, book-like reading experience. Use when viewing markdown files or directories in browser.
Background HTTP server rendering markdown files with calm, book-like reading experience.
This skill requires npm dependencies. Run one of the following:
# Option 1: Install via ClaudeKit CLI (recommended)
ck init # Runs install.sh which handles all skills
# Option 2: Manual installation
cd .claude/skills/markdown-novel-viewer
npm install
Dependencies: marked, highlight.js, gray-matter
Without installation, you'll get Error 500: Error rendering markdown.
Universal viewer - pass ANY path and view it:
# View a markdown file
node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
--file ./plans/my-plan/plan.md \
--open
# Browse a directory
node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
--dir ./plans \
--host 0.0.0.0 \
--open
# Background mode
node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
--file ./README.md \
--background
# Stop all running servers
node $HOME/.claude/skills/markdown-novel-viewer/scripts/server.cjs --stop
Use /preview for quick access:
/preview plans/my-plan/plan.md # View markdown file
/preview plans/ # Browse directory
/preview --stop # Stop server
T - Toggle themeS - Toggle sidebarLeft/Right - Navigate phasesEscape - Close sidebar (mobile)| Option | Description | Default |
|---|---|---|
--file <path> |
Markdown file to view | - |
--dir <path> |
Directory to browse | - |
--port <number> |
Server port | 3456 |
--host <addr> |
Host to bind (0.0.0.0 for remote) |
localhost |
--open |
Auto-open browser | false |
--background |
Run in background | false |
--stop |
Stop all servers | - |
scripts/
├── server.cjs # Main entry point
└── lib/
├── port-finder.cjs # Dynamic port allocation
├── process-mgr.cjs # PID file management
├── http-server.cjs # Core HTTP routing (/view, /browse)
├── markdown-renderer.cjs # MD→HTML conversion
└── plan-navigator.cjs # Plan detection & nav
assets/
├── template.html # Markdown viewer template
├── novel-theme.css # Combined light/dark theme
├── reader.js # Client-side interactivity
├── directory-browser.css # Directory browser styles
| Route | Description |
|---|---|
/view?file=<path> |
Markdown file viewer |
/browse?dir=<path> |
Directory browser |
/assets/* |
Static assets |
/file/* |
Local file serving (images) |
http, fs, path, netmarked, highlight.js, gray-matter (installed via npm install)Light mode variables in assets/novel-theme.css:
--bg-primary: #faf8f3; /* Warm cream */
--accent: #8b4513; /* Saddle brown */
Dark mode:
--bg-primary: #1a1a1a; /* Near black */
--accent: #d4a574; /* Warm gold */
--content-width: 720px;
To access from another device on your network:
# Start with 0.0.0.0 to bind to all interfaces
node server.cjs --file ./README.md --host 0.0.0.0 --port 3456
When using --host 0.0.0.0, the server auto-detects your local network IP and includes it in the output:
{
"success": true,
"url": "http://localhost:3456/view?file=...",
"networkUrl": "http://192.168.2.75:3456/view?file=...",
"port": 3456
}
Use networkUrl to access from other devices on the same network.
Port in use: Server auto-increments to next available port (3456-3500)
Images not loading: Ensure image paths are relative to markdown file
Server won't stop: Check /tmp/md-novel-viewer-*.pid for stale PID files
Remote access denied: Use --host 0.0.0.0 to bind to all interfaces