[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

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