6.7 KiB
6.7 KiB
MDHelper 帮助文档阅读器设计方案
1. 项目目标
MDHelper 是一个用 Python 编写的本地帮助文档阅读器,文档主体由 Markdown 文件组成。项目默认读取根目录下的 sample.md 和 docs/ 目录中的更多手册文件,并支持以下内容:
- 普通 Markdown 文本、标题、列表、引用、链接
- Markdown 表格
- 伪代码和代码块高亮
- 图片显示:PNG、JPG、JPEG、WEBP、BMP、GIF
- 音频播放:MP3、WAV、OGG
- 动画/视频播放:GIF、MP4、WEBM、MOV 等浏览器可播放格式
- 左侧文档目录、正文阅读区、搜索、历史导航
2. 推荐技术路线
推荐采用桌面应用架构:
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,可增强代码块、任务列表、提示块等语法 |
最小可运行依赖建议:
PySide6
markdown-it-py
Pygments
Pillow
如果需要更好的 HTML 后处理和打包:
beautifulsoup4
lxml
PyInstaller
watchdog
rapidfuzz
4. 推荐项目结构
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. 核心界面设计
主窗口建议分为三块:
+-------------------------------------------------------+
| 工具栏:后退 前进 首页 搜索框 字号 主题 刷新 |
+----------------------+--------------------------------+
| 文档树 | 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 的渲染流程
打开 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 图片语法引用音频和视频,例如:


渲染器应识别扩展名:如果目标是音频或视频,就不要生成 <img>,而是替换为对应播放器。
7. 伪代码展示方案
伪代码建议继续使用 fenced code block:
```pseudocode
BEGIN
SET sum = 0
FOR i = 1 TO 10 DO
sum = sum + i
END FOR
END
```
实现方式:
- 对
pseudocode、pseudo、text使用 Pygments 的文本 lexer 或自定义 CSS。 - 给代码块加上
language-pseudocodeclass。 - CSS 中使用等宽字体、浅色背景、行距和边框,保证算法步骤清晰。
8. 链接和路径规则
建议约定:
- 文档链接使用相对路径:
[用户手册](docs/user_manual.md)。 - 媒体资源放在
media/或文档同级目录。 - 内部锚点使用标准 Markdown 锚点:
#2-表格示例。 - 点击
.md链接时由应用拦截,加载目标 Markdown。 - 点击外部
http/https链接时调用系统浏览器打开。
9. 后续实现步骤
- 建立
mdhelper/包和requirements.txt。 - 实现主窗口:左侧
QTreeView,右侧QWebEngineView。 - 实现 Markdown 渲染器,先保证
sample.md完整显示。 - 实现媒体链接替换:图片、GIF、音频、视频。
- 扫描
docs/,生成文档树。 - 实现 Markdown 内链跳转和外部链接打开。
- 增加搜索、主题、字号、最近阅读。
- 用 PyInstaller 打包为独立桌面程序。