Add gitignore and initial project files

2026-05-29 12:46:34 +08:00
commit f9e323f70a
20 changed files with 3216 additions and 0 deletions
@@ -0,0 +1,177 @@
+# webook
+
+📖 一个命令行工具，将 Markdown 笔记目录渲染为 Web 预览页面。
+
+## 特性
+
+- **双栏布局** — 左侧文件导航树 + 右侧内容预览
+- **自动导航** — 启动时递归扫描目录结构，生成可折叠的文件树
+- **元信息展示** — 显示笔记标题、创建时间、修改时间、字数统计
+- **浅/暗主题** — 一键切换，主题偏好自动保存到 localStorage
+- **可隐藏侧边栏** — 专注于阅读内容
+- **搜索过滤** — 侧边栏顶部搜索框，快速过滤文件（快捷键 `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 全部语法：标题、表格、代码块、引用、列表、任务列表等
+- 代码块自动语法高亮
+
+### 主题切换
+
+- 点击工具栏 `🌙` / `☀️` 按钮切换浅/暗主题
+- 选择会自动保存，下次打开保持
+
+### 移动端
+
+- 在手机上浏览时，侧边栏默认隐藏
+- 点击右下角浮动按钮打开侧边栏
+- 点击遮罩层或选文件后自动关闭
+
+## 自定义主题
+
+通过 `--theme` 参数传入外部 CSS 文件路径（支持相对路径和绝对路径），CSS 文件必须是有效的 CSS。建议参考 `public/style.css` 中的 CSS 变量：
+
+```css
+:root {
+  --bg-primary: #ffffff;
+  --bg-secondary: #f8f9fa;
+  --text-primary: #212529;
+  --text-secondary: #6c757d;
+  --border-color: #dee2e6;
+  --accent-color: #4a90d9;
+  /* ... */
+}
+
+[data-theme="dark"] {
+  --bg-primary: #1a1b1e;
+  --text-primary: #c1c2c5;
+  /* ... */
+}
+```
+
+## 目录结构要求
+
+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