shen 8dae91c2ca fix: protect editor content and harden document exports
Protect pending edits on window close, keep save-as paths and drafts consistent,
copy relative image resources, reject oversized table imports without truncation,
and preserve independent preview scrolling during refresh.

Archive rendered MHTML resources with portable references and embedded local
fonts. Preserve existing outputs on export cancellation or failure. Convert
editor match positions and filter directory results in linear passes.

Include the previously completed editor image/table/history improvements,
undoable replacement, export snapshots, shared page settings, and cancellable
PDF/Word export workflow. Update documentation and version to 0.3.1.

Validation: 142 pytest cases passed; GUI smoke, improvements integration, and
offline MHTML/scroll reliability smoke checks passed.
2026-10-29 18:22:42 +08:00
2026-05-25 17:12:00 +08:00
2026-05-26 18:05:10 +08:00
2026-05-26 18:05:10 +08:00

MDHelper

当前版本:0.3.1

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

当前能力

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

当前渲染路径

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

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

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

当前导航设计

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

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

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

编辑模式注意事项

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

  • 阅读模式只显示正文,左侧大纲按需点击跳转。
  • 编辑模式保留源码编辑、左侧大纲、分屏预览和保存冲突检测。
  • 编辑预览刷新使用防抖,避免每次输入都完整重建 HTML。
  • 分屏按源码段落双向同步滚动,可关闭;支持粘贴截图、拖入图片及图形化表格编辑。
  • 全部替换和历史版本恢复可撤销;安全保存保留最近 20 个保存前版本。
  • 四种导出均使用当前编辑内容。Word / PDF 共用纸张、方向、页边距、目录及页眉页脚设置,并提供导出前检查和可取消的生成流程。

快捷键

快捷键 功能
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-<版本号>-x64.exe(版本号自动读取),同目录包含 SHA256 校验文件。 默认按当前用户安装,提供开始菜单入口、可选桌面快捷方式,以及 Windows 卸载入口。 程序运行时无需单独安装 Python 或 Pandoc。

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

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

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

启动优化

  • 使用目录式程序和安装包,Qt、Pandoc 等资源只在安装时解压一次。
  • 欢迎页和阅读器共用固定标签容器;程序在显示主窗口前完成常驻浏览器初始化,随后一次性显示完整界面。首次打开文档只切换容器内部页面,不重建或重新挂接 Windows 原生控件。
  • 关闭全部文档后保留一个隐藏阅读器供后续复用;Windows 渲染后端由 Qt WebEngine 自动选择。
  • 先显示主窗口,后台扫描初始目录;去掉读取设置前的重复扫描和打开初始文件时的重复扫描。
  • 普通文档不加载公式、图表运行库;公式与图表按页面内容分别加载。
  • 缓存阅读样式、脚本和高亮样式;仅在使用 PDF 页码解析时加载相关依赖。
  • 启动日志记录模块导入之后到窗口显示的耗时;该时间不包含进程启动和模块导入。

依赖

核心依赖已写入 requirements.txt:

PySide6==6.11.1
markdown-it-py==4.2.0
tinycss2==1.5.1
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。
  • 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。
S
Description
No description provided
Readme 271 MiB
Languages
Python 92%
PowerShell 4.2%
JavaScript 1.7%
CSS 1.5%
Lua 0.5%
Other 0.1%