220 lines
5.1 KiB
Markdown
220 lines
5.1 KiB
Markdown
# webook
|
||
|
||
📖 一个命令行工具，将 Markdown 笔记目录渲染为 Web 预览页面。
|
||
|
||
## 特性
|
||
|
||
- **双栏布局** — 左侧文件导航树 + 右侧内容预览
|
||
- **自动导航** — 启动时递归扫描目录结构，生成可折叠的文件树
|
||
- **元信息展示** — 显示笔记标题、创建时间、修改时间、字数统计
|
||
- **主题包机制** — 内置多套主题，主题与明暗模式分离，方便后续扩展
|
||
- **可隐藏侧边栏** — 专注于阅读内容
|
||
- **搜索过滤** — 侧边栏顶部搜索框，快速过滤文件（快捷键 `Ctrl+K` / `Cmd+K`）
|
||
- **代码高亮** — 基于 highlight.js，支持 190+ 编程语言
|
||
- **本地图片** — 自动重写相对路径图片链接，支持本地静态资源
|
||
- **热更新** — 文件变更时自动刷新浏览器（WebSocket）
|
||
- **响应式设计** — 移动端自动适配
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install -g webook
|
||
```
|
||
|
||
或本地开发：
|
||
|
||
```bash
|
||
git clone <repo-url>
|
||
cd webook
|
||
npm install
|
||
npm link # 将 webook 链接到全局
|
||
```
|
||
|
||
## 使用
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
# 预览当前目录下的 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` | 显示版本号 | — |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 最小化使用
|
||
webook
|
||
|
||
# 完整参数
|
||
webook ~/Documents/notes --port=8080 --host=0.0.0.0 --title="我的笔记" --open
|
||
|
||
# 使用自定义主题
|
||
webook ./docs --theme=./my-theme.css
|
||
```
|
||
|
||
## 页面功能
|
||
|
||
### 侧边栏
|
||
|
||
- **文件树**：自动递归生成，目录可折叠/展开
|
||
- **搜索**：输入关键词实时过滤文件，按 `Esc` 清空搜索
|
||
- **隐藏**：点击工具栏 `☰` 按钮或使用快捷键
|
||
|
||
### 内容区
|
||
|
||
- 显示笔记标题、创建时间、修改时间、字数
|
||
- 支持 Markdown 全部语法：标题、表格、代码块、引用、列表、任务列表等
|
||
- 代码块自动语法高亮
|
||
|
||
### 主题切换
|
||
|
||
- 顶部下拉框可切换内置主题包
|
||
- 点击工具栏 `🌙` / `☀︎` 按钮切换浅/暗模式
|
||
- 主题包与明暗模式都会自动保存，下次打开保持
|
||
|
||
### 移动端
|
||
|
||
- 在手机上浏览时，侧边栏默认隐藏
|
||
- 点击右下角浮动按钮打开侧边栏
|
||
- 点击遮罩层或选文件后自动关闭
|
||
|
||
## 主题扩展
|
||
|
||
### 内置主题目录
|
||
|
||
每个主题都放在独立文件夹下，便于后续新增、替换和维护：
|
||
|
||
```text
|
||
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` 示例：
|
||
|
||
```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`：
|
||
|
||
```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 文件路径（支持相对路径和绝对路径），会在内置主题之后加载，适合做局部覆盖：
|
||
|
||
```bash
|
||
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` 字段：
|
||
|
||
```json
|
||
{
|
||
"name": "@wu2kong/webook",
|
||
...
|
||
}
|
||
```
|
||
|
||
然后：
|
||
|
||
```bash
|
||
npm login
|
||
npm publish --access public
|
||
```
|
||
|
||
发布后，用户可以通过以下命令安装：
|
||
|
||
```bash
|
||
npm install -g @wu2kong/webook
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: Node.js + Express
|
||
- **Markdown 渲染**: markdown-it
|
||
- **代码高亮**: highlight.js
|
||
- **文件监听**: chokidar
|
||
- **热更新**: WebSocket (ws)
|
||
- **CLI**: commander
|
||
|
||
## License
|
||
|
||
MIT
|