Files
MDHelper/README.md
T

161 lines
7.3 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.2.1`
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 目录。
- 多标签页阅读,支持后退/前进、书签、最近文件和恢复滚动位置。
- 左侧文件树支持按用户选择的文件类型过滤,搜索支持标题、文件名和正文全文搜索。
- 当前页查找支持上一个/下一个命中并显示命中数量。
- 自动刷新当前文档、已打开文档和引用资源;外部修改后会重新读取并渲染。
- 可配置主题颜色、主题背景、正文字号倍率、鼠标滚轮速度、纸张宽度、自动刷新策略和非预览文件打开策略。
- 提供“样式”菜单,支持内置文档样式和自定义样式文件,样式可配置字体、缩进、行距、段前段后间距等。
- 图形样式支持磅值/中文字号、字体颜色、字符间距、对齐、左右和特殊缩进、同样式段落间距及分页控制;三个 DOCX 导出引擎均保留这些设置。高级 CSS 仅用于阅读器及 HTML/PDF。
- 导出支持 PDF、HTML、DOCX、MHTML;DOCX 可选择 `pandoc` 或 `python-docx` 相关实现。
- 图片点击放大,支持缩放、旋转、适应窗口、原始大小、保存图片和在文件夹中显示。
- 表格支持横向滚动和一键复制。
- 支持导入/导出配置 JSON,便于迁移主题、书签、最近文件、阅读位置、样式和外部程序映射。
- 提供文档检查命令,用于扫描缺失的本地链接和媒体资源。
- 运行日志保存到用户可写目录,打包 exe 后也能记录启动和运行状态。
## 当前渲染路径
阅读模式下,当前实现路径是:
```text
打开 .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` | 刷新当前文档 |
## 运行
在项目根目录执行:
```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。
首次缺少 Inno Setup 时会从官方来源下载、校验发布者签名并安装到 `pack\.tools`;后续构建复用。
需要可用的 64 位 Python 3.10+;兼容当前项目的两种 `mdhelper_env` 目录布局。
安装程序位于 `pack\output\MDHelper-Setup-0.2.1-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
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。
- 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。