markdown-novel-viewer

This skill requires npm dependencies. Run one of the following:

```bash

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

• Markdown files → novel-reader UI with serif fonts, warm theme
• Directories → file listing browser with clickable links

```bash

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

```bash

/preview plans/my-plan/plan.md # View markdown file

/preview plans/ # Browse directory

/preview --stop # Stop server

```

Novel Theme

• Warm cream background (light mode)
• Dark mode with warm gold accents
• Libre Baskerville serif headings
• Inter body text, JetBrains Mono code
• Maximum 720px content width

Directory Browser

• Clean file listing with emoji icons
• Markdown files link to viewer
• Folders link to sub-directories
• Parent directory navigation (..)
• Light/dark mode support

Plan Navigation

• Auto-detects plan directory structure
• Sidebar shows all phases with status indicators
• Previous/Next navigation buttons
• Keyboard shortcuts: Arrow Left/Right

Keyboard Shortcuts

• T - Toggle theme
• S - Toggle sidebar
• Left/Right - Navigate phases
• Escape - Close sidebar (mobile)

| Option | Description | Default |

| ----------------- | ----------------------------------- | --------- |

| --file | Markdown file to view | - |

| --dir | Directory to browse | - |

| --port | Server port | 3456 |

| --host | 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= | Markdown file viewer |

| /browse?dir= | Directory browser |

| /assets/* | Static assets |

| /file/* | Local file serving (images) |

• Node.js built-in: http, fs, path, net
• npm: marked, highlight.js, gray-matter (installed via npm install)

Theme Colors (CSS Variables)

Light mode variables in assets/novel-theme.css:

```css

--bg-primary: #faf8f3; / Warm cream /

--accent: #8b4513; / Saddle brown /

```

Dark mode:

```css

--bg-primary: #1a1a1a; / Near black /

--accent: #d4a574; / Warm gold /

```

Content Width

```css

--content-width: 720px;

```

To access from another device on your network:

```bash

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

```json

{

"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

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed