[IMPORTANT] Use
TaskCreate
to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Quick Summary

Goal: Background HTTP server that renders markdown files with a calm, book-like reading UI and browses directories.

Workflow:

Start Server — Point at a markdown file or directory with CLI options
View Content — Novel-themed reader (serif fonts, warm colors) or directory browser
Navigate Plans — Auto-detects plan structures with sidebar, phase status, keyboard shortcuts

Key Rules:

Requires
```
npm install
```
before first use (marked, highlight.js, gray-matter)
Use
```
/preview
```
slash command for quick access
Supports background mode, remote access via
```
--host 0.0.0.0
```

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof.

markdown-novel-viewer

Background HTTP server rendering markdown files with calm, book-like reading experience.

⚠️ Installation Required

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.

Purpose

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

Quick Start

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

Slash Command

Use

/preview

for quick access:

bash

/preview plans/my-plan/plan.md    # View markdown file
/preview plans/                   # Browse directory
/preview --stop                   # Stop server

Features

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)

CLI Options

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	-

Architecture

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

HTTP Routes

Route	Description
`/view?file=<path>`	Markdown file viewer
`/browse?dir=<path>`	Directory browser
`/assets/*`	Static assets
`/file/*`	Local file serving (images)

Dependencies

Node.js built-in:
```
http
```
,
```
fs
```
,
```
path
```
,
```
net
```

npm:

marked

highlight.js

gray-matter

(installed via

npm install

)

Customization

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;

Remote Access

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.

Troubleshooting

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

IMPORTANT Task Planning Notes (MUST FOLLOW)

Always plan and break work into many small todo tasks
Always add a final review todo task to verify work quality and identify fixes/enhancements

markdown-novel-viewer

NPX Install

Tags

SKILL.md Content

Quick Summary

markdown-novel-viewer

⚠️ Installation Required

Purpose

Quick Start

Slash Command

Features

Novel Theme

Directory Browser

Plan Navigation

Keyboard Shortcuts

CLI Options

Architecture

HTTP Routes

Dependencies

Customization

Theme Colors (CSS Variables)

Content Width

Remote Access

Troubleshooting