# MDHelper 当前版本:`0.5.4` MDHelper 是一个本地 Markdown / 代码文档阅读器,使用 PySide6 构建桌面窗口,用 Qt WebEngine 展示由 Markdown 转换得到的 HTML 页面。它面向本地项目文档、技术手册、源码说明和离线帮助文件,重点是离线可用、多标签阅读、全文搜索、样式管理和导出。 0.5.4 修复样式与表格检查发现的 17 项问题:悬浮复制按钮、复制失败提示与嵌套表格复制;表格底色、隔行底纹及无边框的跨端一致性;列表续段编号、嵌套缩进、引用与列表的样式优先级;旧代码基准在 Word 中的联动;旧 CSS 的 `!important`、无效声明回退、嵌套下划线及预设面板刷新。保留旧配置兼容和强调保护方案,启动路径保持稳定。三个 Word 导出引擎继续使用可统一修改的命名样式;组合段落的单一基准和“随所在文字颜色”的处理限制详见[用户手册](docs/user_manual.md)。 ## 当前能力 - 打开文件夹或单个文件,支持启动参数直接传入文件夹名或文件路径。 - 支持同时运行多个程序窗口,分别查看不同文件夹,互不影响。 - 浏览 Markdown、HTML/网页文件,并可在设置中选择展示 Python、C/C++、Fortran 等代码文件。 - Markdown 支持标题、表格、引用、任务列表、提示块、链接、图片、GIF、音频、视频、代码块、Mermaid 图表和数学公式。 - 兼容中文标点紧邻双星号的加粗写法,例如 `**注意:**请先核对`,阅读器与 Word 导出均可正确显示。 - 数学公式支持 KaTeX 和 MathJax,可在菜单中切换。 - 代码块和代码文件使用 Pygments 高亮,代码块支持行号、复制、展开/收起。 - Python 文件可提取类/函数作为目录;C/C++ 文件可提取基础函数、类、结构体目录;Fortran 文件可提取 program、module、type、subroutine、function 目录。 - 多标签页阅读,支持后退/前进、书签、最近文件和恢复滚动位置。 - 按项目恢复上次标签顺序、当前文件、编辑模式和分屏状态;后台标签在点击后加载。“文件”菜单可关闭启动恢复。 - “工具 → 检查文档链接与图片”后台检查项目中的 Markdown/HTML 本地引用及章节锚点;双击结果定位源码,可随时取消。 - 文件树重命名会预览并同步更新 Markdown/HTML 引用、已打开标签和导航记录;操作前保留备份,失败时恢复。 - 保存发生外部冲突时,可对照磁盘与编辑内容,逐段选择并编辑合并结果;取消不会丢失编辑内容。 - “文件 → 批量与合并导出”支持排序后导出多份 Word/PDF,或合成带统一目录、页码和样式的文档;合并时处理图片路径和 Markdown 章节链接。 - “工具 → 项目样式与导出预设”保存各项目的字体、段落、高级 CSS 和页面设置;切换项目自动恢复,模板可导入、导出。 - 左侧文件树支持按用户选择的文件类型过滤,搜索支持标题、文件名和正文全文搜索。 - 当前页查找支持上一个/下一个命中并显示命中数量。 - 自动刷新当前文档、已打开文档和引用资源;外部修改后会重新读取并渲染。 - 可配置主题颜色、主题背景、正文字号倍率、鼠标滚轮速度、纸张宽度、自动刷新策略和非预览文件打开策略。 - 提供“样式”菜单,支持内置文档样式和自定义样式文件,样式可配置字体、缩进、行距、段前段后间距等。 - “样式 → 样式面板”按 Markdown 语义区分正文、六级标题、引用、三类列表、代码块、表头/单元格以及加粗、强调、删除线、链接和行内代码。支持名称、同类型基准样式、当前段落提示、已用样式筛选及实际阅读预览。 - 图形样式与高级 CSS 双向同步,支持字体、字符装饰、背景、段落、列表标记及表格边框/内边距。旧配置和项目预设自动兼容。三个 DOCX 引擎均输出共享命名样式,可在 Word 样式面板统一修改;动态 CSS、阴影及条件选择器等扩展效果继续用于阅读器及 HTML/PDF。 - 导出支持 PDF、HTML、DOCX、MHTML;DOCX 可选择 `pandoc` 或 `python-docx` 相关实现。 - 退出时检查未保存内容;另存为到其他目录会复制相对引用图片。MHTML 保存已渲染的图片、公式、图表及样式资源,支持离线携带。 - 图片点击放大,支持缩放、旋转、适应窗口、原始大小、保存图片和在文件夹中显示。 - 表格按内容分配列宽,长文字和网址可换行,宽表格支持横向滚动;移入或聚焦时显示复制按钮。提供网格、仅横线、无边框和可选隔行底纹,并同步到 Word 表格样式;支持跨页重复表头和行跨页设置。 - 支持导入/导出配置 JSON,便于迁移主题、书签、最近文件、阅读位置、样式和外部程序映射。 - 提供文档检查命令,用于扫描缺失的本地链接和媒体资源。 - 运行日志保存到用户可写目录,打包 exe 后也能记录启动和运行状态。 ## 当前渲染路径 阅读模式下,当前实现路径是: ```text 打开 .md / 代码文件 -> 读取源文件文本 -> MarkdownRenderer 转换为完整 HTML 字符串 -> 拼接 reader.css、reader.js、公式/图表资源引用 -> QWebEngineView.setHtml(html, baseUrl) 可视化 -> 文件变化、样式变化、主题变化或手动刷新时重新生成 HTML 并 setHtml ``` 正常滚动浏览时不会重新转译 Markdown,也不会重新生成 HTML。滚动阶段由 Qt WebEngine 内部的 Chromium 渲染;应用只按固定低频保存滚动坐标,用于重新打开或历史返回时恢复位置。 ## 当前导航设计 左侧导航栏提供两个页签: - `目录`:显示当前文件夹中的文档、搜索框和搜索结果。 - `大纲`:显示当前文档的标题层级,点击标题时跳转。 大纲不会跟随正文滚动高亮。阅读页不生成页面内大纲或阅读进度条,也不在滚动时搜索当前标题、计算进度或通过 WebChannel 连续回传状态。这能避免长文档滚动时的额外计算和界面同步。 ## 编辑模式注意事项 编辑模式和阅读模式会区别处理: - 阅读模式只显示正文,左侧大纲按需点击跳转。 - 编辑模式保留源码编辑、左侧大纲、分屏预览和保存冲突检测。 - 编辑预览刷新使用防抖,避免每次输入都完整重建 HTML。 - 分屏按源码段落双向同步滚动,可关闭;支持粘贴截图、拖入图片及图形化表格编辑。 - 全部替换和历史版本恢复可撤销;安全保存保留最近 20 个保存前版本。 - 四种导出均使用当前编辑内容。Word / PDF 共用纸张、方向、页边距、目录及页眉页脚设置,并提供导出前检查和可取消的生成流程。 ## 项目设置与批量导出 - 工作现场在正常退出或切换项目时保存;未保存内容仍由原有草稿恢复流程保护。指定启动文件时优先打开该文件。 - 启用“以当前设置启用项目默认”后,字体、段落和页面修改自动保存在当前项目;未启用的项目使用全局默认。模板是独立副本,修改一个项目不会改动其他项目。 - 样式预设 JSON 包含字体、核心样式/高级 CSS 和页面设置,不包含项目路径、书签或草稿。高级 CSS 在 Word 中仍受其排版能力限制,导出前会提示不支持的效果。 - 批量导出使用当前编辑内容;分别导出时文件名带顺序编号。全部转换成功后才发布输出,目标文件在导出期间发生变化会停止替换。 - 合并导出按文件分章,保留同名标题的独立目标,图片按各自原文档目录解析。Word 目录需要在 Word 中“更新域”以计算最终页码。内嵌 HTML、Mermaid 等限制会继续出现在导出前检查中。 - 重命名备份位于 `%LOCALAPPDATA%\MDHelper\rename-backups`;每次操作的 `manifest.json` 记录原路径,编号 `.bak` 文件保存原始内容。 ## 快捷键 | 快捷键 | 功能 | |---|---| | `Ctrl+O` | 打开文件夹或文件 | | `Ctrl+P` | 导出当前文档为 PDF | | `Ctrl+D` | 添加当前文档/章节为书签 | | `Ctrl+F` | 查找当前页 | | `Ctrl+Shift+F` | 全文搜索 | | `Ctrl+E` | 编辑当前 Markdown | | `Ctrl+S` | 编辑模式保存 | | `F5` | 刷新当前文档 | ## 运行 在项目根目录执行: ```powershell .\mdhelper_env\Scripts\python.exe -m mdhelper ``` 启动时直接打开指定文件或文件夹: ```powershell .\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md .\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject ``` 也可以执行: ```powershell .\mdhelper_env\Scripts\python.exe .\run_mdhelper.py ``` 检查文档中的本地链接和媒体文件: ```powershell .\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root . ``` 运行测试: ```powershell .\mdhelper_env\Scripts\python.exe -m pytest .\mdhelper_env\Scripts\python.exe .\tests\gui_smoke.py ``` 一键生成 Windows 安装程序(推荐): ```powershell .\pack_installer.cmd ``` 也可直接双击根目录的 `pack_installer.cmd`。脚本自动检查依赖、运行回归测试、生成程序目录并制作安装 EXE;原有 `pack\_installer.cmd` 入口仍可使用。 首次缺少 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` 不再更新。打包后可执行: ```powershell .\dist\MDHelper\MDHelper.exe --check --project-root . ``` 完整构建说明见 [pack/README.md](pack/README.md)。 ## 启动优化 - 使用目录式程序和安装包,Qt、Pandoc 等资源只在安装时解压一次。 - 欢迎页和阅读器共用固定标签容器;程序在显示主窗口前完成常驻浏览器初始化,随后一次性显示完整界面。首次打开文档只切换容器内部页面,不重建或重新挂接 Windows 原生控件。 - 关闭全部文档后保留一个隐藏阅读器供后续复用;Windows 渲染后端由 Qt WebEngine 自动选择。 - 先显示主窗口,后台扫描初始目录;去掉读取设置前的重复扫描和打开初始文件时的重复扫描。 - 普通文档不加载公式、图表运行库;公式与图表按页面内容分别加载。 - 缓存阅读样式、脚本和高亮样式;仅在使用 PDF 页码解析时加载相关依赖。 - 启动日志记录模块导入之后到窗口显示的耗时;该时间不包含进程启动和模块导入。 ## 依赖 核心依赖已写入 `requirements.txt`: ```text 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。 - 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。