markdown-novel-viewer

Original：🇺🇸 English
Translated
14 scripts

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

34installs
Sourceduc01226/easyplatform
Added on

NPX Install

npx skill4agent add duc01226/easyplatform markdown-novel-viewer

Tags

Translated version includes tags in frontmatter
markdown-viewercli-toolhttp-servermarkdown-rendererdocument-preview

SKILL.md Content

View Translation Comparison →
[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:
  1. Start Server — Point at a markdown file or directory with CLI options
  2. View Content — Novel-themed reader (serif fonts, warm colors) or directory browser
  3. 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

OptionDescriptionDefault
--file <path>
Markdown file to view-
--dir <path>
Directory to browse-
--port <number>
Server port3456
--host <addr>
Host to bind (
0.0.0.0
for remote)		localhost
--open
Auto-open browserfalse
--background
Run in backgroundfalse
--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

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