webook/README.md

webook

📖 一个命令行工具，将 Markdown 笔记目录渲染为 Web 预览页面。

特性

• 双栏布局 — 左侧文件导航树 + 右侧内容预览
• 自动导航 — 启动时递归扫描目录结构，生成可折叠的文件树
• 元信息展示 — 显示笔记标题、创建时间、修改时间、字数统计
• 主题包机制 — 内置多套主题，主题与明暗模式分离，方便后续扩展
• 可隐藏侧边栏 — 专注于阅读内容
• 搜索过滤 — 侧边栏顶部搜索框，快速过滤文件（快捷键 Ctrl+K / Cmd+K）
• 代码高亮 — 基于 highlight.js，支持 190+ 编程语言
• 本地图片 — 自动重写相对路径图片链接，支持本地静态资源
• 热更新 — 文件变更时自动刷新浏览器（WebSocket）
• 响应式设计 — 移动端自动适配

安装

npm install -g webook

或本地开发：

git clone <repo-url>
cd webook
npm install
npm link   # 将 webook 链接到全局

使用

基本用法

# 预览当前目录下的 Markdown 笔记
webook

# 预览指定目录
webook ~/my-notes

# 指定端口
webook ~/my-notes --port=3000

# 指定监听地址和网站标题
webook ~/my-notes --host=0.0.0.0 --title="我的知识库"

参数说明

参数	说明	默认值
<dir>	笔记根目录路径	当前目录 .
--port, -p <number>	监听端口（被占用时自动递增）	8000
--host, -h <address>	监听地址	127.0.0.1
--title, -t <title>	网站标题	根目录名
--theme <path>	额外叠加的自定义 CSS 文件路径	无
--open	启动后自动打开浏览器	false
--version, -V	显示版本号	—

示例

# 最小化使用
webook

# 完整参数
webook ~/Documents/notes --port=8080 --host=0.0.0.0 --title="我的笔记" --open

# 使用自定义主题
webook ./docs --theme=./my-theme.css

页面功能

侧边栏

• 文件树：自动递归生成，目录可折叠/展开
• 搜索：输入关键词实时过滤文件，按 Esc 清空搜索
• 隐藏：点击工具栏 ☰ 按钮或使用快捷键

内容区

• 显示笔记标题、创建时间、修改时间、字数
• 支持 Markdown 全部语法：标题、表格、代码块、引用、列表、任务列表等
• 代码块自动语法高亮

主题切换

• 顶部下拉框可切换内置主题包
• 点击工具栏 🌙 / ☀︎ 按钮切换浅/暗模式
• 主题包与明暗模式都会自动保存，下次打开保持

移动端

• 在手机上浏览时，侧边栏默认隐藏
• 点击右下角浮动按钮打开侧边栏
• 点击遮罩层或选文件后自动关闭

主题扩展

内置主题目录

每个主题都放在独立文件夹下，便于后续新增、替换和维护：

public/themes/
├── default/
│   ├── manifest.json
│   ├── theme.css
│   ├── highlight-light.css
│   └── highlight-dark.css
└── paper/
    ├── manifest.json
    ├── theme.css
    ├── highlight-light.css
    └── highlight-dark.css

manifest.json 示例：

{
  "id": "paper",
  "label": "Paper",
  "defaultMode": "light",
  "stylesheet": "theme.css",
  "highlight": {
    "light": "highlight-light.css",
    "dark": "highlight-dark.css"
  }
}

theme.css 通过 data-theme-id 和 data-color-mode 覆盖变量。建议参考 public/themes/default/theme.css：

html[data-theme-id="paper"][data-color-mode="light"] {
  --bg: #f3ece1;
  --text: #3f2f21;
  --brand: #8a5a2b;
  --body-bg: linear-gradient(180deg, #fff8ed 0%, #f3ece1 100%);
  /* ... */
}

html[data-theme-id="paper"][data-color-mode="dark"] {
  --bg: #17120d;
  --text: #f1e4d4;
  --brand: #d1a16c;
  /* ... */
}

外部覆盖样式

通过 --theme 参数传入外部 CSS 文件路径（支持相对路径和绝对路径），会在内置主题之后加载，适合做局部覆盖：

webook ./docs --theme=./my-theme.css
webook ./docs --theme=/absolute/path/to/my-theme.css

目录结构要求

webook 只扫描 .md 和 .markdown 文件。目录推荐按主题分组：

my-notes/
├── README.md           # 首页（如果存在会自动加载）
├── 编程/
│   ├── JavaScript.md
│   └── Python.md
├── 阅读/
│   └── 读书笔记.md
└── 工具/
    └── Git常用命令.md

• 隐藏文件（. 开头）和 node_modules 会被自动跳过
• 目录和文件均按名称字母排序（中文按拼音）

npm 发布

要将 webook 发布到 npm（例如 @wu2kong/webook），修改 package.json 中的 name 字段：

{
  "name": "@wu2kong/webook",
  ...
}

然后：

npm login
npm publish --access public

发布后，用户可以通过以下命令安装：

npm install -g @wu2kong/webook

技术栈

• 后端: Node.js + Express
• Markdown 渲染: markdown-it
• 代码高亮: highlight.js
• 文件监听: chokidar
• 热更新: WebSocket (ws)
• CLI: commander

License

MIT