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

161 lines
6.3 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
当前版本:`0.2.0`
MDHelper 是一个本地 Markdown / 代码文档阅读器,使用 PySide6 构建桌面窗口,用 Qt WebEngine 展示由 Markdown 转换得到的 HTML 页面。它面向本地项目文档、技术手册、源码说明和离线帮助文件,重点是离线可用、多标签阅读、全文搜索、样式管理和导出。
## 当前能力
- 打开文件夹或单个文件,支持启动参数直接传入文件夹名或文件路径。
- 支持同时运行多个程序窗口,分别查看不同文件夹,互不影响。
- 浏览 Markdown、HTML/网页文件,并可在设置中选择展示 Python、C/C++ 等代码文件。
- Markdown 支持标题、表格、引用、任务列表、提示块、链接、图片、GIF、音频、视频、代码块、Mermaid 图表和数学公式。
- 数学公式支持 KaTeX 和 MathJax,可在菜单中切换。
- 代码块和代码文件使用 Pygments 高亮,代码块支持行号、复制、展开/收起。
- Python 文件可提取类/函数作为目录;C/C++ 文件可提取基础函数、类、结构体目录。
- 多标签页阅读,支持后退/前进、书签、最近文件和恢复滚动位置。
- 左侧文件树支持按用户选择的文件类型过滤,搜索支持标题、文件名和正文全文搜索。
- 当前页查找支持上一个/下一个命中并显示命中数量。
- 自动刷新当前文档、已打开文档和引用资源;外部修改后会重新读取并渲染。
- 可配置主题颜色、主题背景、正文字号倍率、鼠标滚轮速度、纸张宽度、自动刷新策略和非预览文件打开策略。
- 提供“样式”菜单,支持内置文档样式和自定义样式文件,样式可配置字体、缩进、行距、段前段后间距等。
- 导出支持 PDF、HTML、DOCX、MHTML;DOCX 可选择 `pandoc` 或 `python-docx` 相关实现。
- 图片点击放大,支持缩放、旋转、适应窗口、原始大小、保存图片和在文件夹中显示。
- 表格支持横向滚动和一键复制。
- 支持导入/导出配置 JSON,便于迁移主题、书签、最近文件、阅读位置、样式和外部程序映射。
- 提供文档检查命令,用于扫描缺失的本地链接和媒体资源。
- 运行日志保存到用户可写目录,打包 exe 后也能记录启动和运行状态。
## 当前渲染路径
阅读模式下,当前实现路径是:
```text
打开 .md / 代码文件
-> 读取源文件文本
-> MarkdownRenderer 转换为完整 HTML 字符串
-> 拼接 reader.css、reader.js、公式/图表资源引用
-> QWebEngineView.setHtml(html, baseUrl) 可视化
-> 文件变化、样式变化、主题变化或手动刷新时重新生成 HTML 并 setHtml
```
正常滚动浏览时不会重新转译 Markdown,也不会重新生成 HTML。滚动阶段主要由 Qt WebEngine 内部的 Chromium 渲染;当前仍会低频把滚动进度和当前章节通过 WebChannel 回传给 Python,用于更新状态栏进度和 Qt 目录树。
## 0.2.0 重点方向
`0.2.0` 的主线目标是提升阅读流畅度,让阅读模式更接近浏览器打开网页的手感。
计划将“当前文档大纲”和“阅读进度”从外部 Qt 控件逐步迁移进 HTML 阅读页:
```text
当前方案:
QWebEngineView 正文滚动
-> JS 计算滚动位置
-> WebChannel 回传 Python
-> Python 更新 QProgressBar 和 QTreeWidget
0.2.0 目标方案:
QWebEngineView 内部同时包含正文、大纲和进度条
-> JS 在网页内部更新目录高亮和进度条
-> Python 只接收低频滚动位置保存、链接打开、图片保存等必要事件
```
预期收益:
- 滚动时减少 Python / Qt 控件更新,降低 WebChannel 往返。
- 大纲高亮、阅读进度和正文滚动都由浏览器内部处理,交互更轻。
- 阅读模式和导出的 HTML 更接近同一套页面结构,便于调试和后续导出增强。
需要保留的边界:
- 左侧文件树、全文搜索、多标签、菜单、设置仍由 Qt 提供。
- 编辑模式保留源码定位能力;预览内大纲点击需要能回传到编辑器定位标题。
- 自动刷新仍以源文件为准,文件变化后重新 Markdown -> HTML。
- 对大文档可以评估“临时 HTML 文件 + load(file://)”作为可选路径,但它不是滚动流畅度的首要优化。
## 编辑模式注意事项
编辑模式和阅读模式会区别处理:
- 阅读模式优先追求浏览器式流畅滚动,大纲和进度条可内嵌到 HTML。
- 编辑模式保留源码编辑、源码目录、分屏预览和保存冲突检测。
- 编辑预览刷新需要防抖,避免每次输入都完整重建 HTML 和大纲。
- 预览中的大纲点击如果要定位源码,需要通过 WebChannel 发送离散事件,而不是持续同步滚动位置。
## 快捷键
| 快捷键 | 功能 |
|---|---|
| `Ctrl+O` | 打开文件夹或文件 |
| `Ctrl+P` | 导出当前文档为 PDF |
| `Ctrl+D` | 添加当前文档/章节为书签 |
| `Ctrl+F` | 查找当前页 |
| `Ctrl+Shift+F` | 全文搜索 |
| `Ctrl+E` | 编辑当前 Markdown |
| `Ctrl+S` | 编辑模式保存 |
| `F5` | 刷新当前文档 |
## 运行
在项目根目录执行:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper
```
启动时直接打开指定文件或文件夹:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject
```
也可以执行:
```powershell
.\mdhelper_env\Scripts\python.exe .\run_mdhelper.py
```
检查文档中的本地链接和媒体文件:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .
```
运行测试:
```powershell
.\mdhelper_env\Scripts\python.exe -m pytest
.\mdhelper_env\Scripts\python.exe .\tests\gui_smoke.py
```
打包为单文件 exe:
```powershell
.\mdhelper_env\Scripts\python.exe -m PyInstaller .\MDHelper.spec --noconfirm --clean
```
生成文件位于 `dist\MDHelper.exe`。打包后建议执行:
```powershell
.\dist\MDHelper.exe --check --project-root .
```
## 依赖
核心依赖已写入 `requirements.txt`:
```text
PySide6==6.11.1
markdown-it-py==4.2.0
Pygments==2.20.0
Pillow==12.2.0
python-docx==1.2.0
PyInstaller==6.20.0
```
外部可选工具:
- `pandoc`:用于增强 DOCX 导出。
- 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。