Initial MDHelper implementation

This commit is contained in:
shenw
2026-05-25 17:12:00 +08:00
commit 50b15b02c7
45 changed files with 11654 additions and 0 deletions
+208
View File
@@ -0,0 +1,208 @@
# MDHelper 帮助文档阅读器设计方案
## 1. 项目目标
MDHelper 是一个用 Python 编写的本地帮助文档阅读器,文档主体由 Markdown 文件组成。项目默认读取根目录下的 `sample.md` 和 `docs/` 目录中的更多手册文件,并支持以下内容:
- 普通 Markdown 文本、标题、列表、引用、链接
- Markdown 表格
- 伪代码和代码块高亮
- 图片显示:PNG、JPG、JPEG、WEBP、BMP、GIF
- 音频播放:MP3、WAV、OGG
- 动画/视频播放:GIF、MP4、WEBM、MOV 等浏览器可播放格式
- 左侧文档目录、正文阅读区、搜索、历史导航
## 2. 推荐技术路线
推荐采用桌面应用架构:
```text
Python 3.13
-> PySide6 / Qt Widgets
-> QWebEngineView 渲染 HTML
-> markdown-it-py 解析 Markdown
-> Pygments 生成代码高亮 HTML
-> 本地 CSS/JS 美化表格、代码块和媒体控件
```
选择 `QWebEngineView` 的主要原因是它内置 Chromium 渲染能力,可以自然展示 HTML5 `<audio>`、`<video>`、GIF 动画、图片、表格和复杂 CSS。相比 `QTextBrowser`,它更适合做包含多媒体内容的帮助文档阅读器。
## 3. 软件框架和软件包清单
### 已在 `mdhelper_env` 中存在的核心包
| 软件包 | 当前环境版本 | 作用 |
|---|---:|---|
| Python | 3.13.13 | 运行环境 |
| PySide6 | 6.11.1 | GUI 框架,提供窗口、菜单、分栏、树形目录、WebEngine |
| PySide6-Addons | 6.11.1 | 包含 QtWebEngine、QtMultimedia 等附加模块 |
| PySide6-Essentials | 6.11.1 | Qt 基础控件和核心模块 |
| shiboken6 | 6.11.1 | PySide6 绑定依赖 |
| markdown-it-py | 4.2.0 | Markdown 解析器 |
| mdurl | 0.1.2 | Markdown 链接解析依赖 |
| Pygments | 2.20.0 | 代码块和伪代码高亮 |
| Pillow | 12.2.0 | 图片元信息读取、缩略图生成、格式检查 |
### 建议补充的可选包
| 软件包 | 是否必需 | 作用 |
|---|---|---|
| beautifulsoup4 | 可选 | 对生成后的 HTML 做二次处理,把音频/视频链接替换为播放器标签 |
| lxml | 可选 | 更快、更稳定的 HTML/XML 处理 |
| PyInstaller | 可选 | 打包为 Windows `.exe` |
| watchdog | 可选 | 监听 Markdown 文件变化,实现自动刷新 |
| rapidfuzz | 可选 | 模糊搜索文档标题和正文 |
| whoosh 或 sqlite FTS5 | 可选 | 建立全文搜索索引 |
| pymdown-extensions | 可选 | 如果改用 Python-Markdown,可增强代码块、任务列表、提示块等语法 |
最小可运行依赖建议:
```text
PySide6
markdown-it-py
Pygments
Pillow
```
如果需要更好的 HTML 后处理和打包:
```text
beautifulsoup4
lxml
PyInstaller
watchdog
rapidfuzz
```
## 4. 推荐项目结构
```text
MDHelper/
sample.md
docs/
README.md
user_manual.md
quick_start.md
...
media/
screenshot.png
animation.gif
demo.mp4
demo.mp3
mdhelper/
__init__.py
app.py # QApplication 入口
main_window.py # 主窗口、菜单、工具栏、分栏
document_tree.py # docs/sample.md 文件树
markdown_renderer.py # Markdown -> HTML
media.py # 媒体类型识别和路径处理
search.py # 标题/全文搜索
history.py # 前进后退和最近阅读
resources/
reader.css
reader.js
requirements.txt
README.md
```
## 5. 核心界面设计
主窗口建议分为三块:
```text
+-------------------------------------------------------+
| 工具栏:后退 前进 首页 搜索框 字号 主题 刷新 |
+----------------------+--------------------------------+
| 文档树 | QWebEngineView 阅读区 |
| - sample.md | |
| - docs/README.md | Markdown 转换后的 HTML |
| - docs/user_manual.md| 图片/音频/视频内嵌播放 |
+----------------------+--------------------------------+
| 状态栏:当前文件、链接地址、加载状态 |
+-------------------------------------------------------+
```
建议功能:
- 文档树:扫描 `sample.md` 和 `docs/**/*.md`。
- 阅读区:用 `QWebEngineView.setHtml(html, baseUrl)` 加载转换后的 HTML。
- 搜索框:先做文件名/标题搜索,后续扩展全文索引。
- 历史导航:记录打开过的 Markdown 文件和锚点。
- 主题切换:浅色/深色 CSS。
- 字号调节:通过注入 CSS 变量控制正文大小。
## 6. Markdown 到 HTML 的渲染流程
```text
打开 md 文件
-> 读取 UTF-8 文本
-> markdown-it-py 解析 Markdown
-> Pygments 处理 fenced code block
-> HTML 后处理:
图片扩展名 -> <img>
音频扩展名 -> <audio controls>
视频扩展名 -> <video controls>
GIF -> <img> 自动播放
-> 拼接 reader.css / reader.js
-> QWebEngineView.setHtml(html, baseUrl=项目根目录)
```
媒体类型判断建议:
| 类型 | 扩展名 | HTML 标签 |
|---|---|---|
| 图片 | `.png` `.jpg` `.jpeg` `.webp` `.bmp` `.svg` | `<img>` |
| GIF 动画 | `.gif` | `<img>` |
| 音频 | `.mp3` `.wav` `.ogg` `.m4a` | `<audio controls>` |
| 视频/动画 | `.mp4` `.webm` `.mov` `.avi` | `<video controls>` |
`sample.md` 当前使用了 Markdown 图片语法引用音频和视频,例如:
```markdown
![背景音乐](media/demo.mp3)
![演示视频](media/demo.mp4)
```
渲染器应识别扩展名:如果目标是音频或视频,就不要生成 `<img>`,而是替换为对应播放器。
## 7. 伪代码展示方案
伪代码建议继续使用 fenced code block:
````markdown
```pseudocode
BEGIN
SET sum = 0
FOR i = 1 TO 10 DO
sum = sum + i
END FOR
END
```
````
实现方式:
- 对 `pseudocode`、`pseudo`、`text` 使用 Pygments 的文本 lexer 或自定义 CSS。
- 给代码块加上 `language-pseudocode` class。
- CSS 中使用等宽字体、浅色背景、行距和边框,保证算法步骤清晰。
## 8. 链接和路径规则
建议约定:
- 文档链接使用相对路径:`[用户手册](docs/user_manual.md)`。
- 媒体资源放在 `media/` 或文档同级目录。
- 内部锚点使用标准 Markdown 锚点:`#2-表格示例`。
- 点击 `.md` 链接时由应用拦截,加载目标 Markdown。
- 点击外部 `http/https` 链接时调用系统浏览器打开。
## 9. 后续实现步骤
1. 建立 `mdhelper/` 包和 `requirements.txt`。
2. 实现主窗口:左侧 `QTreeView`,右侧 `QWebEngineView`。
3. 实现 Markdown 渲染器,先保证 `sample.md` 完整显示。
4. 实现媒体链接替换:图片、GIF、音频、视频。
5. 扫描 `docs/`,生成文档树。
6. 实现 Markdown 内链跳转和外部链接打开。
7. 增加搜索、主题、字号、最近阅读。
8. 用 PyInstaller 打包为独立桌面程序。