Files
MDHelper/README.md
T

6.8 KiB
Raw Blame History

MDHelper

当前版本:0.2.0

MDHelper 是一个本地 Markdown / 代码文档阅读器,使用 PySide6 构建桌面窗口,用 Qt WebEngine 展示由 Markdown 转换得到的 HTML 页面。它面向本地项目文档、技术手册、源码说明和离线帮助文件,重点是离线可用、多标签阅读、全文搜索、样式管理和导出。

当前能力

  • 打开文件夹或单个文件,支持启动参数直接传入文件夹名或文件路径。
  • 支持同时运行多个程序窗口,分别查看不同文件夹,互不影响。
  • 浏览 Markdown、HTML/网页文件,并可在设置中选择展示 Python、C/C++、Fortran 等代码文件。
  • Markdown 支持标题、表格、引用、任务列表、提示块、链接、图片、GIF、音频、视频、代码块、Mermaid 图表和数学公式。
  • 数学公式支持 KaTeX 和 MathJax,可在菜单中切换。
  • 代码块和代码文件使用 Pygments 高亮,代码块支持行号、复制、展开/收起。
  • Python 文件可提取类/函数作为目录;C/C++ 文件可提取基础函数、类、结构体目录;Fortran 文件可提取 program、module、type、subroutine、function 目录。
  • 多标签页阅读,支持后退/前进、书签、最近文件和恢复滚动位置。
  • 左侧文件树支持按用户选择的文件类型过滤,搜索支持标题、文件名和正文全文搜索。
  • 当前页查找支持上一个/下一个命中并显示命中数量。
  • 自动刷新当前文档、已打开文档和引用资源;外部修改后会重新读取并渲染。
  • 可配置主题颜色、主题背景、正文字号倍率、鼠标滚轮速度、纸张宽度、自动刷新策略和非预览文件打开策略。
  • 提供“样式”菜单,支持内置文档样式和自定义样式文件,样式可配置字体、缩进、行距、段前段后间距等。
  • 导出支持 PDF、HTML、DOCX、MHTML;DOCX 可选择 pandoc 或 python-docx 相关实现。
  • 图片点击放大,支持缩放、旋转、适应窗口、原始大小、保存图片和在文件夹中显示。
  • 表格支持横向滚动和一键复制。
  • 支持导入/导出配置 JSON,便于迁移主题、书签、最近文件、阅读位置、样式和外部程序映射。
  • 提供文档检查命令,用于扫描缺失的本地链接和媒体资源。
  • 运行日志保存到用户可写目录,打包 exe 后也能记录启动和运行状态。

当前渲染路径

阅读模式下,当前实现路径是:

打开 .md / 代码文件
  -> 读取源文件文本
  -> MarkdownRenderer 转换为完整 HTML 字符串
  -> 拼接 reader.css、reader.js、公式/图表资源引用
  -> QWebEngineView.setHtml(html, baseUrl) 可视化
  -> 文件变化、样式变化、主题变化或手动刷新时重新生成 HTML 并 setHtml

正常滚动浏览时不会重新转译 Markdown,也不会重新生成 HTML。滚动阶段由 Qt WebEngine 内部的 Chromium 渲染;应用只按固定低频保存滚动坐标,用于重新打开或历史返回时恢复位置。

当前导航设计

左侧导航栏提供两个页签:

  • 目录:显示当前文件夹中的文档、搜索框和搜索结果。
  • 大纲:显示当前文档的标题层级,点击标题时跳转。

大纲不会跟随正文滚动高亮。阅读页不生成页面内大纲或阅读进度条,也不在滚动时搜索当前标题、计算进度或通过 WebChannel 连续回传状态。这能避免长文档滚动时的额外计算和界面同步。

编辑模式注意事项

编辑模式和阅读模式会区别处理:

  • 阅读模式只显示正文,左侧大纲按需点击跳转。
  • 编辑模式保留源码编辑、左侧大纲、分屏预览和保存冲突检测。
  • 编辑预览刷新使用防抖,避免每次输入都完整重建 HTML。

快捷键

快捷键 功能
Ctrl+O 打开文件夹或文件
Ctrl+P 导出当前文档为 PDF
Ctrl+D 添加当前文档/章节为书签
Ctrl+F 查找当前页
Ctrl+Shift+F 全文搜索
Ctrl+E 编辑当前 Markdown
Ctrl+S 编辑模式保存
F5 刷新当前文档

运行

在项目根目录执行:

.\mdhelper_env\Scripts\python.exe -m mdhelper

启动时直接打开指定文件或文件夹:

.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject

也可以执行:

.\mdhelper_env\Scripts\python.exe .\run_mdhelper.py

检查文档中的本地链接和媒体文件:

.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .

运行测试:

.\mdhelper_env\Scripts\python.exe -m pytest
.\mdhelper_env\Scripts\python.exe .\tests\gui_smoke.py

一键生成 Windows 安装程序(推荐):

.\pack\_installer.cmd

也可直接双击 pack\_installer.cmd。脚本自动检查依赖、运行回归测试、生成程序目录并制作安装 EXE。 首次缺少 Inno Setup 时会从官方来源下载、校验发布者签名并安装到 pack\.tools;后续构建复用。 需要可用的 64 位 Python 3.10+;兼容当前项目的两种 mdhelper_env 目录布局。

安装程序位于 pack\output\MDHelper-Setup-0.2.0-x64.exe(版本号自动读取),同目录包含 SHA256 校验文件。 默认按当前用户安装,提供开始菜单入口、可选桌面快捷方式,以及 Windows 卸载入口。 程序运行时无需单独安装 Python 或 Pandoc。

开发用程序目录为 dist\MDHelper\,必须保留整个目录,不能只复制其中的 EXE。 旧的 dist\MDHelper.exe 不再更新。打包后可执行:

.\dist\MDHelper\MDHelper.exe --check --project-root .

完整构建说明见 pack/README.md。

启动优化

  • 使用目录式程序和安装包,Qt、Pandoc 等资源只在安装时解压一次。
  • 欢迎页使用普通 Qt 控件;打开文档时才创建浏览器页面。
  • 先显示主窗口,后台扫描初始目录;去掉读取设置前的重复扫描和打开初始文件时的重复扫描。
  • 普通文档不加载公式、图表运行库;公式与图表按页面内容分别加载。
  • 缓存阅读样式、脚本和高亮样式;仅在使用 PDF 页码解析时加载相关依赖。
  • 启动日志记录模块导入之后到窗口显示的耗时;该时间不包含进程启动和模块导入。

依赖

核心依赖已写入 requirements.txt:

PySide6==6.11.1
markdown-it-py==4.2.0
Pygments==2.20.0
Pillow==12.2.0
python-docx==1.2.0
pypdf==6.14.2
PyInstaller==6.20.0

配套工具:

  • pandoc:用于增强 DOCX 导出,正式 EXE 已内置,无需用户另行安装或配置 PATH。
  • 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。