name: markdown-novel-viewer
description: View markdown files with calm, book-like reading experience via HTTP server. Use for long-form content, documentation preview, novel reading, report viewing, distraction-free reading.

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 .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

Mermaid.js Diagrams

• Auto-renders mermaid code blocks as diagrams
• Theme-aware (light/dark mode support)
• Error display with source preview for debugging

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

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

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

Mermaid.js Diagrams

Usage

Use fenced code blocks with mermaid language:

```mermaid
pie title Traffic Sources
    "Organic" : 45
    "Direct" : 30
    "Referral" : 25
```

Supported Diagram Types

Validating Mermaid Snippets

Quick validation: Use the Mermaid Live Editor to test syntax.

Common errors and fixes:

Fixing Common Issues

1. Flowchart arrows

%% Wrong: A -> B
%% Correct:
flowchart LR
    A --> B

2. Pie chart values

%% Wrong: "Label": 50%
%% Correct:
pie title Sales
    "Product A" : 50
    "Product B" : 30

3. XY Chart data format

xychart-beta
    title "Monthly Sales"
    x-axis [Jan, Feb, Mar]
    y-axis "Revenue" 0 --> 100
    bar [30, 45, 60]

4. Sequence diagram participants

sequenceDiagram
    participant A as Client
    participant B as Server
    A->>B: Request
    B-->>A: Response

Debug Mode

When a diagram fails to render, the viewer shows:
- Error message
- Expandable source code preview
- Line number where parsing failed (when available)

Fix the syntax and refresh the page to re-render.