209 lines
6.7 KiB
Markdown
209 lines
6.7 KiB
Markdown
# 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
|
||

|
||

|
||
```
|
||
|
||
渲染器应识别扩展名:如果目标是音频或视频,就不要生成 `<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 打包为独立桌面程序。
|