Files
MDHelper/README.md
T

185 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MDHelper
当前版本:`0.5.3`
MDHelper 是一个本地 Markdown / 代码文档阅读器,使用 PySide6 构建桌面窗口,用 Qt WebEngine 展示由 Markdown 转换得到的 HTML 页面。它面向本地项目文档、技术手册、源码说明和离线帮助文件,重点是离线可用、多标签阅读、全文搜索、样式管理和导出。
0.5.3 修复独立 CSS 选择器被合并、Word 列表缩进被编号覆盖,以及嵌套字符样式相同初始值丢失显式覆盖的问题;补齐旧基准解除继承、Markdown 表格列对齐、引用内宽松列表、图形设置与 `!important` 同步、列表段落间距、无效 CSS 回退及无边框导出。保留旧配置兼容和强调保护方案,启动路径保持稳定。三个 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 保存已渲染的图片、公式、图表及样式资源,支持离线携带。
- 图片点击放大,支持缩放、旋转、适应窗口、原始大小、保存图片和在文件夹中显示。
- 表格支持横向滚动和一键复制。
- 支持导入/导出配置 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。
- 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。