Files
MDHelper/docs/user_manual.md
T
2026-06-18 12:30:37 +08:00

229 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MDHelper 用户手册
MDHelper 是一个本地 Markdown / 代码文档阅读器,适合阅读项目说明、技术手册、源码旁文档和离线帮助文件。它使用 PySide6 提供桌面窗口,用 Qt WebEngine 渲染 Markdown 转换后的 HTML 页面,并在本地完成全文搜索、样式管理、导出和自动刷新。
当前版本:`0.2.0`
## 1. 适用场景
- 查看本地项目中的 Markdown、HTML、Python、C/C++ 文档或源码说明。
- 在大文件夹中按文件类型过滤文档,并全文搜索标题、文件名和正文。
- 阅读带有表格、图片、GIF、音频、视频、代码块、Mermaid 图表和数学公式的 Markdown。
- 对 Markdown 做简单编辑、分屏预览、保存、另存为和草稿恢复。
- 将当前 Markdown 导出为 PDF、HTML、DOCX 或 MHTML。
- 为不同文档保存阅读样式、字体、段落格式和纸张宽度。
## 2. 启动与打开文件
直接启动:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper
```
启动时打开指定文件夹或文件:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject
.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
```
打包版可以同样接收路径参数:
```powershell
.\dist\MDHelper.exe D:\CODE\SomeProject
```
MDHelper 支持同时运行多个程序窗口。不同窗口可以打开不同文件夹,标签页、搜索、设置和自动刷新状态互不影响。
## 3. 主界面
界面主要分为三部分:
| 区域 | 功能 |
|---|---|
| 左侧文档栏 | 打开文件夹、刷新、搜索、文件树、文件类型过滤结果。 |
| 中间标签页 | 阅读、编辑、预览、媒体页面和欢迎页。 |
| 文档内容右侧 | 网页内文档大纲,随正文滚动高亮当前章节。 |
默认阅读模式会把文档大纲和阅读进度放在网页内部,减少 Qt 控件同步,让滚动更接近浏览器网页。右侧旧 Qt 目录栏默认关闭;只有在设置中关闭网页内大纲并启用外部目录栏时才显示。
## 4. 阅读 Markdown
Markdown 支持:
- 标题、段落、列表、引用、表格、任务列表。
- 提示块:`note`、`tip`、`important`、`warning`、`caution`。
- 代码块高亮、行号、复制、展开/收起。
- Mermaid 图表。
- KaTeX 或 MathJax 数学公式。
- 本地图片、GIF、音频和视频。
- 本地链接跳转和外部链接打开。
阅读页内的文档大纲位于正文右侧,点击章节可跳转。窄窗口下大纲会自动折叠或隐藏。
右下角阅读进度条会跟随主题改变颜色。进度条只在网页内部更新,Python 端只低频保存滚动位置。
## 5. 纸张宽度与每行字数
在 `工具 - 设置` 中可以调整 `纸张宽度`:
| 选项 | 说明 |
|---|---|
| `A4(x1)` | 默认宽度,接近 A4 页面阅读宽度。 |
| `A4 × 1.25` | 稍宽,适合宽屏阅读。 |
| `A4 × 1.5` | 更宽,每行显示更多文字。 |
| `A4 × 1.75` | 宽屏技术文档阅读。 |
| `A4 × 2` | 最大内置宽度,适合代码和宽表格。 |
纸张宽度只改变正文最大宽度,不改变字号。因此宽度越大,同一行显示的文字越多。编辑器预览、阅读页、代码文件阅读和本地文本预览都会跟随该设置。
## 6. 展示文件类型
默认只展示 Markdown 和网页文档。可在 `工具 - 设置 - 展示文件类型` 中启用:
- Markdown / 网页
- Python
- C / C++
启用代码文件后:
- 左侧文件树会显示对应扩展名的文件。
- 全文搜索会包含安全大小内的代码文件。
- Python 文件会提取类和函数作为目录。
- C/C++ 文件会用轻量规则提取基础函数、类和结构体目录。
- 大型代码文件会限制读取和高亮,避免文件夹很大时卡顿。
## 7. 查找与搜索
左侧搜索框用于搜索当前文件夹下的文档:
- 搜索标题、文件名和正文。
- 上方按钮可执行搜索、上一个、下一个。
- 搜索结果会定位到左侧文件树中的文件。
当前页查找使用 `Ctrl+F`。编辑模式下,源码查找和阅读页查找相互独立。
## 8. 编辑 Markdown
打开 Markdown 后,可使用 `Ctrl+E` 或菜单进入编辑模式。编辑器支持:
- 源码 / 预览 / 分屏三种视图。
- Markdown 语法高亮。
- 行号和当前行高亮。
- 查找、替换、区分大小写、全词匹配。
- 插入标题、加粗、斜体、代码块、表格、链接、图片、提示块、Mermaid、公式。
- `Ctrl+S` 保存。
- 另存为。
- 自动保存草稿和恢复草稿。
- 保存前检测磁盘文件是否被外部程序修改,避免覆盖外部编辑。
编辑预览中的网页内大纲可点击定位源码标题。预览刷新使用防抖机制,避免每次按键都重新渲染。
## 9. 样式管理
菜单栏 `样式` 用于管理文档展示样式:
- 可切换内置样式。
- 可创建自定义样式。
- 自定义样式可编辑、导出、导入和删除。
- 内置样式不可删除。
图形界面可设置不同对象的字体和段落格式,例如:
- 正文段落、一级到六级标题、列表项、引用、代码块、表格。
- 中文字体和英文字体分开设置。
- 字号、加粗、斜体。
- 行间距:倍数或磅。
- 段前 / 段后间距:倍数或磅。
- 首行缩进和悬挂缩进:按字符设置。
纸张宽度是全局阅读设置,内置样式不再写死正文宽度,会跟随纸张宽度变化。
## 10. 媒体与表格
图片:
- 点击可打开灯箱。
- 支持放大、缩小、旋转、适应窗口、原始大小、保存图片、在文件夹中显示。
音频和视频:
- 支持内置预览。
- 对无法内置播放的格式,可选择系统播放器或记住指定程序。
表格:
- 宽表格支持横向滚动。
- 可一键复制为制表符分隔文本。
## 11. 自动刷新
默认开启自动刷新。推荐刷新延迟为 `1 秒`:
- 既能及时看到外部编辑器保存后的变化。
- 又能避免文件连续保存时频繁重渲染。
设置中可选择:
| 模式 | 说明 |
|---|---|
| 当前文档、资源和目录 | 当前文档、引用图片/媒体、文件树和搜索索引都更新。 |
| 当前文档和引用资源 | 更新当前文档和其引用资源。 |
| 仅当前文档 | 只刷新当前正在看的文件。 |
| 关闭 | 不自动刷新。 |
MDHelper 读取文档时不会独占文件,外部程序仍可修改文件。
## 12. 导出
当前文档可导出为:
- PDF
- HTML
- DOCX
- MHTML
DOCX 导出可选择 `pandoc` 或 `python-docx` 相关实现。导出的 HTML 默认不包含网页内阅读进度条,避免把阅读状态写进文档。
## 13. 配置与迁移
MDHelper 会保存:
- 最近文件和上次打开文件夹。
- 主题、背景、字号、滚轮速度、纸张宽度。
- 文档样式和自定义样式。
- 书签和滚动位置。
- 文件类型展示设置。
- 外部程序映射。
可通过配置导入/导出 JSON 在不同机器之间迁移。
## 14. 快捷键
| 快捷键 | 功能 |
|---|---|
| `Ctrl+O` | 打开文件夹或文件 |
| `Ctrl+P` | 导出 PDF |
| `Ctrl+D` | 添加书签 |
| `Ctrl+F` | 当前页查找 |
| `Ctrl+Shift+F` | 全文搜索 |
| `Ctrl+E` | 编辑当前 Markdown |
| `Ctrl+S` | 编辑模式保存 |
| `Ctrl+H` | 编辑模式查找替换 |
| `F5` | 刷新当前文档 |
## 15. 命令行检查
扫描文档中的本地链接和媒体资源:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .
```
打包版:
```powershell
.\dist\MDHelper.exe --check --project-root .
```