Back to Details

markdown-novel-viewer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
[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.
[重要提示] 开始工作前请使用
TaskCreate
将所有工作拆分为小任务，包括每个文件读取的任务。这可以避免长文件导致的上下文丢失。对于简单任务，AI必须询问用户是否跳过拆分。

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.
目标： 后台运行的HTTP服务器，可渲染Markdown文件、提供舒缓的类书籍阅读UI，同时支持目录浏览。
工作流程：
  1. 启动服务器 — 通过CLI选项指定要打开的Markdown文件或目录
  2. 查看内容 — 小说风格阅读器（衬线字体、暖色调）或目录浏览器
  3. 导航计划 — 自动检测计划结构，支持侧边栏、阶段状态、键盘快捷键
核心规则：
  • 首次使用前需要执行
    npm install
    安装依赖（marked、highlight.js、gray-matter）
  • 使用
    /preview
    斜杠命令快速访问
  • 支持后台模式，通过
    --host 0.0.0.0
    参数支持远程访问
请保持怀疑态度，运用批判性思维、顺序思考，每一项主张都需要可追溯的证明。

markdown-novel-viewer

markdown-novel-viewer

Background HTTP server rendering markdown files with calm, book-like reading experience.
后台运行的HTTP服务器，用于渲染Markdown文件，提供舒缓的、类书籍的阅读体验。

⚠️ Installation Required

⚠️ 需要安装依赖

This skill requires npm dependencies. Run one of the following:
bash
undefined
本skill需要安装npm依赖。 运行以下命令之一：
bash
undefined

Option 1: Install via ClaudeKit CLI (recommended)

Option 1: Install via ClaudeKit CLI (recommended)

ck init # Runs install.sh which handles all skills
ck init # Runs install.sh which handles all skills

Option 2: Manual installation

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**.
cd .claude/skills/markdown-novel-viewer npm install

**依赖：** `marked`, `highlight.js`, `gray-matter`

未安装的话会报错 **500错误：渲染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
通用查看器，传入任意路径即可查看：
  • Markdown文件 → 采用衬线字体、暖色调主题的小说阅读器UI
  • 目录 → 带可点击链接的文件列表浏览器

Quick Start

快速开始

bash
undefined
bash
undefined

View a markdown file

查看一个Markdown文件

node .claude/skills/markdown-novel-viewer/scripts/server.cjs
--file ./plans/my-plan/plan.md
--open
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
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
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
undefined
node $HOME/.claude/skills/markdown-novel-viewer/scripts/server.cjs --stop
undefined

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
使用
/preview
快速访问：
bash
/preview plans/my-plan/plan.md    # 查看Markdown文件
/preview plans/                   # 浏览目录
/preview --stop                   # 停止服务器

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
  • 暖奶油色背景（浅色模式）
  • 带暖金色点缀的深色模式
  • Libre Baskerville 衬线字体标题
  • Inter 正文字体，JetBrains Mono 代码字体
  • 最大内容宽度720px

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
  • 带emoji图标的清爽文件列表
  • Markdown文件跳转至阅读器
  • 文件夹跳转至子目录
  • 上级目录导航（..）
  • 支持浅色/深色模式

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)
  • T
    - 切换主题
  • S
    - 切换侧边栏
  • 左/右方向键
    - 切换阶段
  • Escape
    - 关闭侧边栏（移动端）

CLI Options

CLI参数

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-
参数说明默认值
--file <path>
要查看的Markdown文件路径-
--dir <path>
要浏览的目录路径-
--port <number>
服务器端口3456
--host <addr>
绑定的主机地址（
0.0.0.0
可支持远程访问）		localhost
--open
自动打开浏览器false
--background
后台运行false
--stop
停止所有服务器-

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
scripts/
├── server.cjs               # 主入口文件
└── lib/
    ├── port-finder.cjs      # 动态端口分配
    ├── process-mgr.cjs      # PID文件管理
    ├── http-server.cjs      # 核心HTTP路由 (/view, /browse)
    ├── markdown-renderer.cjs # MD转HTML转换
    └── plan-navigator.cjs   # 计划检测与导航

assets/
├── template.html            # Markdown阅读器模板
├── novel-theme.css          # 深浅主题合并样式
├── reader.js                # 客户端交互逻辑
├── directory-browser.css    # 目录浏览器样式

HTTP Routes

HTTP路由

RouteDescription
/view?file=<path>
Markdown file viewer
/browse?dir=<path>
Directory browser
/assets/*
Static assets
/file/*
Local file serving (images)
路由说明
/view?file=<path>
Markdown文件阅读器
/browse?dir=<path>
目录浏览器
/assets/*
静态资源
/file/*
本地文件服务（图片等）

Dependencies

依赖

  • Node.js built-in: 
    http
    , 
    fs
    , 
    path
    , 
    net
  • npm: 
    marked
    , 
    highlight.js
    , 
    gray-matter
    (installed via 
    npm install
    )
  • Node.js内置模块：
    http
    , 
    fs
    , 
    path
    , 
    net
  • npm依赖：
    marked
    , 
    highlight.js
    , 
    gray-matter
    （通过
    npm install
    安装）

Customization

自定义

Theme Colors (CSS Variables)

主题颜色（CSS变量）

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 */
assets/novel-theme.css
中的浅色模式变量：
css
--bg-primary: #faf8f3; /* 暖奶油色 */
--accent: #8b4513; /*  saddle brown */
深色模式变量：
css
--bg-primary: #1a1a1a; /* 近黑色 */
--accent: #d4a574; /* 暖金色 */

Content Width

内容宽度

css
--content-width: 720px;
css
--content-width: 720px;

Remote Access

远程访问

To access from another device on your network:
bash
undefined
要从同一网络下的其他设备访问：
bash
undefined

Start with 0.0.0.0 to bind to all interfaces

使用0.0.0.0绑定所有网卡接口启动

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.
node server.cjs --file ./README.md --host 0.0.0.0 --port 3456

使用`--host 0.0.0.0`启动时，服务器会自动检测本地网络IP并输出到结果中：

```json
{
    "success": true,
    "url": "http://localhost:3456/view?file=...",
    "networkUrl": "http://192.168.2.75:3456/view?file=...",
    "port": 3456
}
使用
networkUrl
即可从同一网络下的其他设备访问。

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
端口被占用：服务器会自动递增查找可用端口（3456-3500范围）
图片加载失败：请确保图片路径是相对于Markdown文件的相对路径
服务器无法停止：检查
/tmp/md-novel-viewer-*.pid
路径下是否有残留的PID文件
远程访问被拒绝：使用
--host 0.0.0.0
参数绑定所有网卡接口
重要任务规划说明（必须遵守）
  • 始终规划并将工作拆分为多个小型待办任务
  • 始终添加最终审核待办任务，验证工作质量，识别需要修复/优化的点