# mdreader

**Repository Path**: yuliqing16/mdreader

## Basic Information

- **Project Name**: mdreader
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# MD Reader

一个基于 Tauri 2.x 的跨平台 Markdown 编辑器桌面应用，提供实时预览、原生桌面菜单和常用文档导航能力。

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Tauri](https://img.shields.io/badge/Tauri-2.x-24C8DB.svg)
![React](https://img.shields.io/badge/React-18-61DAFB.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6.svg)

## ✨ 特性

- 📁 **文件管理** - 侧边栏浏览、创建、删除文件和文件夹
- ✏️ **实时编辑** - Markdown 编辑与实时预览同步
- 🧭 **原生菜单** - 文件、编辑、视图、导出、导航、帮助菜单全部接入桌面原生菜单栏
- 💾 **文件工作流** - 支持新建、打开、打开文件夹、保存、另存为、重命名、关闭、最近打开
- 🔎 **文档导航** - 支持快速打开、文档大纲、上下标题跳转、顶部/底部跳转
- 🪟 **视图控制** - 支持编辑/预览/分栏切换、侧边栏显隐、滚动同步、缩放、状态栏、全屏
- 🛠️ **编辑辅助** - 支持查找、替换、撤销、重做
- 📤 **导出** - 支持导出 HTML、PDF 和 DOCX
- 📚 **帮助面板** - 提供 Markdown 语法速查、快捷键说明、关于信息
- 💾 **快捷键保存** - 支持 Ctrl+S / Cmd+S 快捷键保存
- 🔒 **未保存提示** - 关闭前检测未保存更改
- 📊 **丰富渲染** - 支持 GFM、数学公式、代码高亮、流程图、Callout、Wikilink、目录生成

## 🛠️ 技术栈

| 部分 | 技术 |
|------|------|
| **前端** | React 18 + TypeScript + Vite |
| **UI 框架** | Ant Design 6.x |
| **Markdown 渲染** | `@uiw/react-md-editor`, `react-markdown` |
| **代码高亮** | `prismjs`, `rehype-prism-plus` |
| **数学公式** | `rehype-katex`, `remark-math` |
| **流程图** | `mermaid` |
| **桌面框架** | Tauri 2.x (Rust) |

## 📦 编译与打包

### 系统要求

#### Linux (Ubuntu/Debian)

```bash
# 安装系统依赖
sudo apt-get update
sudo apt-get install -y \
    libwebkit2gtk-4.1-dev \
    libgtk-3-dev \
    libjavascriptcoregtk-4.1-dev \
    libsoup-3.0-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev \
    libxdo-dev \
    build-essential \
    curl \
    wget \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev \
    gnome-video-effects \
    gnome-video-effects-extra
```

#### Windows

```powershell
# 安装 Visual Studio 2022 (包含 C++ 桌面开发)
# 下载地址：https://visualstudio.microsoft.com/

# 安装 WebView2 (Windows 10/11 自带)
# https://developer.microsoft.com/en-us/microsoft-edge/webview2/
```

#### macOS

```bash
# 安装 Xcode Command Line Tools
xcode-select --install
```

### 安装 Rust 和 Node.js

```bash
# 安装 Rust (所有平台)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 验证 Rust 安装
rustc --version
cargo --version

# 安装 Node.js (建议使用 LTS 版本)
# https://nodejs.org/ 或使用 nvm
```

### 安装项目依赖

```bash
npm install
```

### 开发模式

```bash
# 启动开发服务器（前端热重载 + Tauri 应用）
npm run tauri dev
```

### 构建发布版本

```bash
# 构建所有平台的应用包
npm run tauri build
```

### 构建产物位置

构建完成后，安装包位于 `src-tauri/target/release/bundle/` 目录：

```
src-tauri/target/release/bundle/
├── deb/                          # Linux Debian/Ubuntu
│   └── MD Reader_1.0.0_amd64.deb
├── appimage/                     # Linux AppImage
│   └── MD Reader-1.0.0-x86_64.AppImage
├── nsis/                         # Windows 安装程序
│   └── MD Reader Setup.exe
└── msi/                          # Windows MSI 安装包
    └── MD Reader.msi
```

### 平台特定构建

#### 仅构建 Linux 包

```bash
npm run tauri build -- --target x86_64-unknown-linux-gnu
```

#### 仅构建 Windows 包（在 Windows 上）

```bash
npm run tauri build -- --target x86_64-pc-windows-msvc
```

### 可用 npm 脚本

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动 Vite 开发服务器 |
| `npm run build` | 构建前端资源 |
| `npm run tauri dev` | 启动 Tauri 开发环境 |
| `npm run tauri build` | 构建并发布应用 |
| `npm run lint` | ESLint 代码检查 |
| `npm run preview` | 预览构建产物 |

## 📁 项目结构

```
mdreader/
├── src/                          # React 前端源码
│   ├── components/               # UI 组件
│   │   ├── Editor/               # Markdown 编辑器
│   │   ├── Preview/              # 预览组件
│   │   ├── Sidebar/              # 侧边栏文件浏览器
│   │   ├── CustomHeader/         # 自定义标题栏
│   │   └── ...                   # 其他组件
│   ├── hooks/                    # 自定义 Hooks
│   │   ├── useMarkdownWorker.ts  # Markdown 处理 Worker
│   │   ├── useDocxExportWorker.ts# DOCX 导出 Worker
│   │   └── ...                   # 其他 Hooks
│   ├── utils/                    # 工具函数
│   │   ├── exportDocument.ts     # 文档导出工具
│   │   ├── exportDocx.ts         # DOCX 导出
│   │   ├── exportHtml.ts         # HTML 导出
│   │   └── ...                   # 其他工具
│   ├── workers/                  # Web Workers
│   │   ├── markdownWorker.ts     # Markdown 解析 Worker
│   │   └── docxExportWorker.ts   # DOCX 导出 Worker
│   ├── menu/                     # 菜单相关
│   ├── App.tsx                   # 主应用组件
│   └── main.tsx                  # 入口文件
├── src-tauri/                    # Tauri Rust 后端
│   ├── src/
│   │   ├── main.rs               # Rust 入口
│   │   ├── lib.rs                # 库入口
│   │   ├── commands.rs           # Tauri 命令实现
│   │   └── menu.rs               # 原生菜单构建
│   ├── capabilities/             # Tauri 2 权限配置
│   ├── icons/                    # 应用图标
│   ├── Cargo.toml                # Rust 依赖配置
│   └── tauri.conf.json           # Tauri 配置
├── docs/                         # 文档
│   └── plans/                    # 开发计划文档
├── tests/                        # 测试文件
├── package.json                  # 前端依赖配置
├── tsconfig.json                 # TypeScript 配置
├── vite.config.ts                # Vite 配置
└── playwright.config.ts          # Playwright E2E 测试配置
```

## 🔧 配置说明

### Tauri 配置 (src-tauri/tauri.conf.json)

```json
{
  "productName": "MD Reader",
  "version": "1.0.0",
  "identifier": "com.mdreader.app",
  "bundle": {
    "targets": ["deb", "appimage", "nsis", "msi"]
  }
}
```

### 权限配置 (src-tauri/capabilities/)

Tauri 2.x 使用能力（Capabilities）系统替代了 1.x 的 allowlist：

```json
{
  "identifier": "default",
  "permissions": [
    "core:default",
    "dialog:default",
    "fs:default",
    "shell:default"
  ]
}
```

## 📝 使用说明

### 菜单概览

- `文件`
  - 新建文件、打开文件、打开文件夹、最近打开、保存、另存为、重命名、关闭、退出
- `编辑`
  - 撤销、重做、查找、查找与替换，以及系统剪切/复制/粘贴/全选
- `视图`
  - 侧边栏显隐、滚动同步开关、编辑/预览/分栏模式、缩放、全屏、状态栏
- `导出`
  - 导出 HTML、导出 PDF、导出 DOCX
- `导航`
  - 快速打开、最近文件、大纲、上下标题、顶部、底部
- `帮助`
  - Markdown 语法速查、快捷键说明、检查更新、关于

### 常用快捷键

| 操作 | 快捷键 |
|------|--------|
| 新建文件 | `Ctrl+N` / `Cmd+N` |
| 打开文件 | `Ctrl+O` / `Cmd+O` |
| 打开文件夹 | `Ctrl+Shift+O` / `Cmd+Shift+O` |
| 保存 | `Ctrl+S` / `Cmd+S` |
| 另存为 | `Ctrl+Shift+S` / `Cmd+Shift+S` |
| 撤销 | `Ctrl+Z` / `Cmd+Z` |
| 重做 | `Ctrl+Shift+Z` / `Cmd+Shift+Z` |
| 切换侧边栏 | `Ctrl+B` / `Cmd+B` |
| 全屏 | `F11` |

### 最近打开与快速打开

- 最近文件和最近文件夹会保存在本地存储中，应用重启后仍然可用
- 原生菜单中的 `最近打开` 会随着最近文件列表实时更新
- `快速打开` 会合并最近文件和当前目录中已加载的 Markdown 文件，支持按文件名或路径搜索

### 导航与大纲

- 预览区标题会自动生成锚点 `id`
- `文档大纲` 可快速跳转到任意标题
- `上一个标题` / `下一个标题` 会基于当前预览滚动位置导航
- `顶部` / `底部` 会滚动当前主视图到对应位置

### 查找与替换

- `查找` 支持上下跳转匹配项
- `查找与替换` 支持替换当前匹配和全部替换

### Markdown 扩展支持

- **GFM** - GitHub Flavored Markdown
- **数学公式** - 使用 `$$` 或 `$` 语法
- **代码高亮** - 支持多种语言
- **流程图** - 使用 Mermaid 语法
- **Callout** - 支持 Note、Tip、Warning、Important、Caution 等提示块
- **Wikilink** - 支持 `[[链接]]` 语法
- **目录生成** - 支持自动生成目录
- **Front Matter** - 支持 YAML 头信息

### 导出功能

- **HTML** - 导出为独立 HTML 文件，图片转为 Base64
- **PDF** - 打印工作流导出
- **DOCX** - 导出为 Word 文档，支持高保真格式

### 快速开始

1. **打开应用** - 启动 MD Reader
2. **打开文件夹** - 点击侧边栏"打开文件夹"按钮
3. **编辑文件** - 点击 `.md` 文件开始编辑
4. **保存文件** - 按 `Ctrl+S` / `Cmd+S` 保存
5. **新建文件/文件夹** - 右键点击目录树

## 🧪 测试

项目使用 Playwright 进行端到端测试：

```bash
# 安装 Playwright 浏览器
npx playwright install

# 运行 E2E 测试
npm run test

# 运行测试并查看报告
npm run test -- --ui
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License