Initial MDHelper implementation
This commit is contained in:
@@ -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
|
||||

|
||||

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