Files
MDHelper/docs/user_manual.md
T

242 lines
9.7 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.1`
## 1. 适用场景
- 查看本地项目中的 Markdown、HTML、Python、C/C++、Fortran 文档或源码说明。
- 在大文件夹中按文件类型过滤文档,并全文搜索标题、文件名和正文。
- 阅读带有表格、图片、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\MDHelper.exe D:\CODE\SomeProject
```
MDHelper 支持同时运行多个程序窗口。不同窗口可以打开不同文件夹,标签页、搜索、设置和自动刷新状态互不影响。
## 3. 主界面
界面主要分为两部分:
| 区域 | 功能 |
|---|---|
| 左侧导航栏 | 在“目录”和“大纲”间切换;目录包含搜索与文件树,大纲显示当前文档标题。 |
| 中间标签页 | 阅读、编辑、预览、媒体页面和欢迎页。 |
阅读页只显示正文,不在网页内部生成大纲或进度条。左侧大纲不会随正文滚动高亮;只有用户点击标题时才执行跳转,避免长文档滚动时持续计算当前位置。
## 4. 阅读 Markdown
Markdown 支持:
- 标题、段落、列表、引用、表格、任务列表。
- 提示块:`note`、`tip`、`important`、`warning`、`caution`。
- 代码块高亮、行号、复制、展开/收起。
- Mermaid 图表。
- KaTeX 或 MathJax 数学公式。
- 本地图片、GIF、音频和视频。
- 本地链接跳转和外部链接打开。
切换左侧的 `大纲` 页签并点击章节即可跳转。滚动位置仍会低频保存,用于重新打开文档时恢复阅读位置。
## 5. 纸张宽度与每行字数
在 `工具 - 设置` 中可以调整 `纸张宽度`:
| 选项 | 说明 |
|---|---|
| `A4(x1)` | 默认宽度,接近 A4 页面阅读宽度。 |
| `A4 × 1.25` | 稍宽,适合宽屏阅读。 |
| `A4 × 1.5` | 更宽,每行显示更多文字。 |
| `A4 × 1.75` | 宽屏技术文档阅读。 |
| `A4 × 2` | 最大内置宽度,适合代码和宽表格。 |
纸张宽度只改变正文最大宽度,不改变字号。因此宽度越大,同一行显示的文字越多。编辑器预览、阅读页、代码文件阅读和本地文本预览都会跟随该设置。
## 6. 展示文件类型
默认只展示 Markdown 和网页文档。可在 `工具 - 设置 - 展示文件类型` 中启用:
- Markdown / 网页
- Python
- C / C++
- Fortran(.f、.for、.f90、.f95)
启用代码文件后:
- 左侧文件树会显示对应扩展名的文件。
- 全文搜索会包含安全大小内的代码文件。
- Python 文件会提取类和函数作为目录。
- C/C++ 文件会用轻量规则提取基础函数、类和结构体目录。
- Fortran 文件会用轻量规则提取 program、module、type、subroutine 和 function 目录。
- 大型代码文件会限制读取和高亮,避免文件夹很大时卡顿。
## 7. 查找与搜索
左侧搜索框用于搜索当前文件夹下的文档:
- 搜索标题、文件名和正文。
- 上方按钮可执行搜索、上一个、下一个。
- 搜索结果会定位到左侧文件树中的文件。
当前页查找使用 `Ctrl+F`。编辑模式下,源码查找和阅读页查找相互独立。
## 8. 编辑 Markdown
打开 Markdown 后,可使用 `Ctrl+E` 或菜单进入编辑模式。编辑器支持:
- 源码 / 预览 / 分屏三种视图。
- Markdown 语法高亮。
- 行号和当前行高亮。
- 查找、替换、区分大小写、全词匹配。
- 插入标题、加粗、斜体、代码块、表格、链接、图片、提示块、Mermaid、公式。
- 点击“转换latex公式到md”,可将全文中的 `\\[` 和 `\\]` 一键转换为 `$$`,并支持回退撤销。
- 打开文件夹后,可通过“文件 → 新建文件”或左侧目录树右键菜单直接创建 `.md` 文件。新文件会在目标目录中自动生成并进入文件名编辑状态,无需打开浏览窗口。
- 左侧目录树支持多选文件;右键单个文件可重命名,右键选择“删除”并确认后可批量移入系统回收站。右键非根文件夹还可在确认后删除该文件夹及其内容。
- `Ctrl+S` 保存。
- 另存为。
- 自动保存草稿和恢复草稿。
- 保存前检测磁盘文件是否被外部程序修改,避免覆盖外部编辑。
编辑时左侧大纲可点击定位源码标题。预览刷新使用防抖机制,避免每次按键都重新渲染。
## 9. 样式管理
菜单栏 `样式` 用于管理文档展示样式:
- 可切换内置样式。
- 可创建自定义样式。
- 自定义样式可编辑、导出、导入和删除。
- 内置样式不可删除。
图形界面可设置不同对象的字体和段落格式,例如:
- 正文段落、一级到六级标题、列表项、引用、代码块、表格。
- 中文字体和英文字体分开设置。
- 字号支持磅(pt)、像素(px)和中文常用字号,例如五号 10.5 磅;可设置加粗、斜体、字体颜色和字符间距。
- 对齐支持左对齐、居中、右对齐和两端对齐。
- 行距支持单倍、1.5 倍、双倍、多倍、固定值和最小值。
- 段前 / 段后间距支持磅、字符(em)或行,可设置同样式段落间不添加间距。
- 左右缩进支持字符、磅或厘米;特殊缩进可选择无、首行或悬挂,首行与悬挂互斥。
- 分页支持与下段同页、段中不分页、段前分页和孤行控制。
“继承”沿用当前文档默认值;数字 0 表示明确清零。复选框方块表示继承、勾选表示开启、空白表示关闭。设置窗口下方提供实时预览;分页效果以 Word 为准。旧样式文件会自动兼容原有的像素字号、字符间距和缩进。
纸张宽度是全局阅读设置,内置样式不再写死正文宽度,会跟随纸张宽度变化。
## 10. 媒体与表格
图片:
- 点击可打开灯箱。
- 支持放大、缩小、旋转、适应窗口、原始大小、保存图片、在文件夹中显示。
音频和视频:
- 支持内置预览。
- 对无法内置播放的格式,可选择系统播放器或记住指定程序。
表格:
- 宽表格支持横向滚动。
- 可一键复制为制表符分隔文本。
## 11. 自动刷新
默认开启自动刷新。推荐刷新延迟为 `1 秒`:
- 既能及时看到外部编辑器保存后的变化。
- 又能避免文件连续保存时频繁重渲染。
设置中可选择:
| 模式 | 说明 |
|---|---|
| 当前文档、资源和目录 | 当前文档、引用图片/媒体、文件树和搜索索引都更新。 |
| 当前文档和引用资源 | 更新当前文档和其引用资源。 |
| 仅当前文档 | 只刷新当前正在看的文件。 |
| 关闭 | 不自动刷新。 |
MDHelper 读取文档时不会独占文件,外部程序仍可修改文件。
## 12. 导出
当前文档可导出为:
- PDF
- HTML
- DOCX
- MHTML
PDF 导出前会显示设置窗口,可分别设置上、下、左、右页边距。导出文件固定使用白色纸张背景,自动移除阅读页大纲和进度条,并在正文前生成带真实页码的目录;正文从目录后的新页面开始。
DOCX 导出可选择 `pandoc` 或 `python-docx` 相关实现。正式安装版已包含 Pandoc,无需用户另行下载或配置 PATH。导出的 HTML 与阅读页一样不包含阅读进度控件。
Pandoc、python-docx 和内置基础导出均保留图形设置中的字体、字号、颜色、字符间距、对齐、缩进、段间距、行距和分页选项。正文、各级标题、列表、引用、代码和表格分别应用对应设置;Markdown 中显式加粗、斜体的局部文本仍保留强调。Word 字号按其支持的半磅精度写入;自动颜色使用 Word 自动文字颜色。
高级 CSS 仅影响阅读器及 HTML/PDF,不能转换为 Word 样式。阅读器是连续页面,固定值/最小值行距及分页效果可能与 Word 显示不同;导出文件分别保留 Word 的固定值、最小值和分页属性。三个引擎的表格、复杂 Markdown、图片或公式支持范围仍按各自能力处理。
## 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\MDHelper.exe --check --project-root .
```