[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, confidence percentages (Idea should be more than 80%).

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:

# 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

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

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

--bg-primary: #faf8f3; /* Warm cream */
--accent: #8b4513; /* Saddle brown */

Dark mode:

--bg-primary: #1a1a1a; /* Near black */
--accent: #d4a574; /* Warm gold */

Content Width

--content-width: 720px;

Remote Access

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.

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

Closing Reminders

MUST break work into small todo tasks using TaskCreate BEFORE starting
MUST search codebase for 3+ similar patterns before creating new code
MUST cite file:line evidence for every claim (confidence >80% to act)
MUST add a final review todo task to verify work quality