markdown-preview-cli（中文版）

一个自包含的 Markdown 预览命令行工具。指定一个文件夹，它就会启动一个本地 Web 应用， 把该文件夹（含所有嵌套子目录）渲染成一个菜单树，每个 Markdown 文件作为叶子节点。 预览支持多种主题与 Mermaid 图表。

• 前端：React + TypeScript + Ant Design（基于 Vite 构建）
• 后端：NestJS + TypeScript（提供 API 与静态 SPA）
• 分发方式：单个 npm 包，对外暴露 mdp 命令

功能特性

• 📁 文件夹 → 菜单树 —— 目录（含所有层级）变成可展开的菜单节点；.md / .markdown / .mdx 文件变成可点击的叶子。
• 🖥️ 两种选择文件夹的方式
  • 本地文件夹（Local） —— 使用浏览器的文件夹选择器（Chromium 上为 File System Access API， 并带 webkitdirectory 回退方案）。由浏览器直接读取文件。
  • 服务端目录（Server） —— 选择后端提供的目录，或输入任意绝对路径；NestJS 后端从磁盘读取， 返回目录树与文件内容。
• 🎨 多种主题 —— GitHub 浅色 / 暗色、VS Code 浅色 / 暗色、Monokai、Tokyo Night。 切换主题只替换 CSS 变量，因此过渡依然顺滑。Ant Design 的界面会自动跟随当前主题。
• 📑 目录（Table of Contents） —— 右侧导航栏列出文档的各级标题；点击可跳转， 滚动时高亮当前所在章节。
• 📋 代码块 —— 每个围栏代码块显示语言徽标，悬停时显示「复制」按钮，点击将原始代码复制到剪贴板。
• 🔗 标题锚点 —— 悬停任意标题会显示 # 链接，点击可复制该小节的深链接。
• 📊 Mermaid 图表 —— 围栏 mermaid 代码块会被渲染为 SVG，并自动套用当前主题配色。
• 🔍 页内搜索 —— 按 Ctrl/Cmd + F（或点击「搜索」按钮）在当前文档中查找文本， 支持命中高亮与上一个 / 下一个跳转。
• 🔤 可调阅读字号 —— 工具栏中的 A- / A+ 缩放文档字体（已持久化）。
• 📈 阅读辅助 —— 顶部进度条跟踪滚动位置；头部显示字数统计与预计阅读时长。
• ⚡ 零配置 CLI —— mdp [folder] 启动服务并自动打开浏览器。

安装

npm install -g markdown-preview-cli

需要 Node.js >= 18。

所有命令都挂在子命令之下 —— 直接运行 mdp（不带参数）会打印帮助：

mdp                        # 显示帮助与可用命令
mdp -V / --version         # 打印当前版本
mdp version                # 打印当前版本（子命令形式）
mdp start [folder]         # 以前台方式启动（阻塞终端）
mdp start [folder] -d      # 以分离的后台方式启动（终端关闭后依然运行）
mdp stop                   # 停止正在运行的服务（前台或后台）
mdp status                 # 显示运行中服务的 pid / url / 启动时间
mdp logs                   # 跟踪查看服务日志

前台 / 后台（Foreground vs Background）

mdp start 默认以前台方式运行 —— 它会阻塞终端、打印 URL，并在你关闭终端或按 Ctrl+C 时停止。 加上 -d / --daemon 会启动一个分离的后台进程，该进程在终端关闭后仍然存活，并可通过 Web UI 或 mdp stop 停止。

注意：mdp status / mdp stop 对两种模式都有效 —— 每个运行中的 mdp 都会写入一份运行时文件， 因此你随时可以从另一个终端查看或停止它。前台服务在终端关闭时也会自行退出，不会成为游离的孤儿进程。

选项

这些选项适用于 mdp start（前台与 -d / --daemon 均适用）。

| 选项 | 默认值 | 说明 | | -------------- | ----------- | ---------------------------------- | | [folder] | — | 要预览的文件夹（服务端模式深链接） | | -p, --port | 7321 | 监听的端口 | | -h, --host | 127.0.0.1 | 绑定的主机（默认仅回环地址） | | --no-open | (关闭) | 禁止自动打开浏览器 | | -d, --daemon | (关闭) | 以分离的后台方式运行 |

当守护进程（-d）运行时，Web UI 头部会显示一个后台运行徽标与一个 关闭后台服务按钮 —— 点击（需确认）即可关闭服务。关闭接口受每个实例独立的令牌保护 （以 HttpOnly + SameSite=Strict 的 Cookie 下发），因此只有同源的 UI 或 mdp stop 能够停止它。

工作原理

markdown-preview-cli
├── bin/mdp.js                 # 薄封装层 -> dist/server/src/cli.js
├── client/                    # React + Ant Design + TS（Vite）
│   └── src/
│       ├── api/               # 后端调用 + 本地文件系统访问
│       ├── components/        # FileTree、MarkdownViewer、Mermaid、Toolbar 等
│       ├── hooks/             # 抽离的 React 生命周期逻辑（深链接、拖拽缩放、页内搜索等）
│       ├── theme/             # 主题引擎：themes / themeEngine / hljsThemes / themeContext / colorUtils
│       │   └── themes.ts      # 主题 token 与 Mermaid 映射
│       └── styles/markdown.css
├── server/                    # NestJS + TS
│   └── src/
│       ├── main.ts            # 启动引导 + 静态 SPA 托管
│       ├── cli.ts             # commander 入口（mdp）
│       └── markdown/          # /api/roots、/api/tree、/api/file 等
├── scripts/copy-public.js     # 把前端构建产物复制进服务端静态目录
├── vite.config.ts
├── nest-cli.json
├── tsconfig.json / tsconfig.server.json
├── .eslintrc.cjs / .prettierrc
└── package.json

React 应用由 Vite 打包进 client/dist，随后 scripts/copy-public.js 将其复制进 dist/server/public。NestJS 服务端把该目录作为静态 SPA 托管，并为 Markdown 后端保留 /api 命名空间。

API

| 方法 | 路径 | 查询参数 | 返回 | | ----- | ------------ | -------- | ---------------------------- | | GET | /api/roots | — | 后端提供的目录列表 | | GET | /api/tree | path | 递归菜单树（目录 + md 文件） | | GET | /api/file | path | 单个文件的原始 Markdown 文本 |

完整端点另含 /api/children（单层懒加载）、/api/count（md 文件计数）、 /api/search（文件名搜索）、/api/asset（图片等静态资源）、 以及 /api/server/info、/api/server/shutdown（守护进程生命周期）。

开发

git clone <repo> && cd markdown-preview-cli
npm install

# 在两个终端分别运行后端（NestJS，带 watch）与前端（Vite 开发服务器，带 HMR）
npm run dev:server   # http://localhost:7321  （API）
npm run dev:client   # http://localhost:5173  （将 /api 代理到 :7321）

# 代码检查 / 格式化 / 类型检查
npm run lint
npm run format
npm run typecheck

# 生产构建（前端 + 服务端 + 复制资源）
npm run build
npm start            # 在 :7321 托管构建好的 SPA 与 API

发布

npm version patch        # 递增版本号
npm publish              # 触发 prepublishOnly -> npm run build

发布的压缩包仅包含 dist/、bin/、package.json 与 README.md（见 files 字段）。 使用者安装到的就是一个开箱即用的 CLI —— React / Ant Design / Mermaid 均已打包在内。

许可证

MIT —— 详见 LICENSE。