Files
MDHelper/MDHelper_design.md
T
2026-05-25 17:12:00 +08:00

6.7 KiB
Raw Blame History

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 图片语法引用音频和视频,例如:

![背景音乐](media/demo.mp3)
![演示视频](media/demo.mp4)

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