# markdown-preview

**Repository Path**: moocsk/markdown-preview

## Basic Information

- **Project Name**: markdown-preview
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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]` 启动服务并自动打开浏览器。

---

## 安装

```bash
npm install -g markdown-preview-cli
```

> 需要 Node.js >= 18。

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

```bash
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`（守护进程生命周期）。

---

## 开发

```bash
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
```

---

## 发布

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

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

## 许可证

MIT —— 详见 [LICENSE](./LICENSE)。