Files
MDHelper/docs/user_manual.md
T

322 lines
23 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 用户手册
MDHelper 是一个本地 Markdown / 代码文档阅读器,适合阅读项目说明、技术手册、源码旁文档和离线帮助文件。它使用 PySide6 提供桌面窗口,用 Qt WebEngine 渲染 Markdown 转换后的 HTML 页面,并在本地完成全文搜索、样式管理、导出和自动刷新。
当前版本:`0.3.1`
## 1. 适用场景
- 查看本地项目中的 Markdown、HTML、Python、C/C++、Fortran 文档或源码说明。
- 在大文件夹中按文件类型过滤文档,并全文搜索标题、文件名和正文。
- 阅读带有表格、图片、GIF、音频、视频、代码块、Mermaid 图表和数学公式的 Markdown。
- 对 Markdown 做简单编辑、分屏预览、保存、另存为和草稿恢复。
- 将当前 Markdown 导出为 PDF、HTML、DOCX 或 MHTML。
- 为不同文档保存阅读样式、字体、段落格式和纸张宽度。
## 2. 启动与打开文件
直接启动:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper
```
启动时打开指定文件夹或文件:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject
.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
```
打包版可以同样接收路径参数:
```powershell
.\dist\MDHelper\MDHelper.exe D:\CODE\SomeProject
```
MDHelper 支持同时运行多个程序窗口。不同窗口可以打开不同文件夹,标签页、搜索、设置和自动刷新状态互不影响。
## 3. 主界面
界面主要分为两部分:
| 区域 | 功能 |
|---|---|
| 左侧导航栏 | 在“目录”和“大纲”间切换;目录包含搜索与文件树,大纲显示当前文档标题。 |
| 中间标签页 | 阅读、编辑、预览、媒体页面和欢迎页。 |
阅读页只显示正文,不在网页内部生成大纲或进度条。左侧大纲不会随正文滚动高亮;只有用户点击标题时才执行跳转,避免长文档滚动时持续计算当前位置。
## 4. 阅读 Markdown
Markdown 支持:
- 标题、段落、列表、引用、表格、任务列表。
- 中文加粗支持 `**先完成一项指标样稿。**选择一个指标` 这类标点后直接接正文的写法,也支持中文引号、括号与嵌套斜体。代码块、行内代码、公式和转义的星号保持原样。
- 提示块:`note`、`tip`、`important`、`warning`、`caution`。
- 代码块高亮、行号、复制、展开/收起。
- Mermaid 图表。
- KaTeX 或 MathJax 数学公式。
- 本地图片、GIF、音频和视频。
- 本地链接跳转和外部链接打开。
切换左侧的 `大纲` 页签并点击章节即可跳转。滚动位置仍会低频保存,用于重新打开文档时恢复阅读位置。
## 5. 纸张宽度与每行字数
在 `工具 - 设置` 中可以调整 `纸张宽度`:
| 选项 | 说明 |
|---|---|
| `A4(x1)` | 默认宽度,接近 A4 页面阅读宽度。 |
| `A4 × 1.25` | 稍宽,适合宽屏阅读。 |
| `A4 × 1.5` | 更宽,每行显示更多文字。 |
| `A4 × 1.75` | 宽屏技术文档阅读。 |
| `A4 × 2` | 最大内置宽度,适合代码和宽表格。 |
纸张宽度只改变正文最大宽度,不改变字号。因此宽度越大,同一行显示的文字越多。编辑器预览、阅读页、代码文件阅读和本地文本预览都会跟随该设置。
## 6. 展示文件类型
默认只展示 Markdown 和网页文档。可在 `工具 - 设置 - 展示文件类型` 中启用:
- Markdown / 网页
- Python
- C / C++
- Fortran(.f、.for、.f90、.f95)
启用代码文件后:
- 左侧文件树会显示对应扩展名的文件。
- 全文搜索会包含安全大小内的代码文件。
- Python 文件会提取类和函数作为目录。
- C/C++ 文件会用轻量规则提取基础函数、类和结构体目录。
- Fortran 文件会用轻量规则提取 program、module、type、subroutine 和 function 目录。
- 大型代码文件会限制读取和高亮,避免文件夹很大时卡顿。
## 7. 查找与搜索
左侧搜索框用于搜索当前文件夹下的文档:
- 搜索标题、文件名和正文。
- 上方按钮可执行搜索、上一个、下一个。
- 搜索结果会定位到左侧文件树中的文件。
当前页查找使用 `Ctrl+F`。编辑模式下,源码查找和阅读页查找相互独立。
## 8. 编辑 Markdown
打开 Markdown 后,可使用 `Ctrl+E` 或菜单进入编辑模式。编辑器支持:
- 源码 / 预览 / 分屏三种视图。
- Markdown 语法高亮。
- 行号和当前行高亮。
- 查找、替换、区分大小写、全词匹配。
- 插入标题、加粗、斜体、代码块、表格、链接、图片、提示块、Mermaid、公式。
- 点击“转换latex公式到md”,可将全文中的 `\\[` 和 `\\]` 一键转换为 `$$`,并支持回退撤销。
- 打开文件夹后,可通过“文件 → 新建文件”或左侧目录树右键菜单直接创建 `.md` 文件。新文件会在目标目录中自动生成并进入文件名编辑状态,无需打开浏览窗口。
- 左侧目录树支持多选文件;右键单个文件可重命名,右键选择“删除”并确认后可批量移入系统回收站。右键非根文件夹还可在确认后删除该文件夹及其内容。
- `Ctrl+S` 保存。
- 另存为。
- 自动保存草稿和恢复草稿。
- 保存前检测磁盘文件是否被外部程序修改,避免覆盖外部编辑。
“全部替换”支持一次撤销,并保留此前的编辑记录。替换文本中的反斜杠按普通字符处理,可直接填写 Windows 路径。
关闭软件时,会先记录所有编辑标签的最新草稿,再提供“保存 / 放弃 / 取消”。选择保存但写入失败时窗口保持打开;选择取消会保留草稿;选择放弃会清除相应草稿。即使尚未等到定时保存草稿,也会检查当前编辑内容。
另存为成功后,后续草稿归属于新文件。若保存失败,编辑器继续使用原路径。另存为到其他文件夹时,相对引用的 Markdown 图片和 HTML `img src` 图片会复制到新文档旁的资源文件夹并更新引用;原文件和原资源保留。引用式图片会转换为等价的行内图片,代码示例不改动。找不到图片或无法复制时会提示,并保留当前编辑内容和原路径。
保存采用完整写入后替换原文件的方式。每个文件路径保留最近 20 个保存前版本,位于 `%LOCALAPPDATA%\MDHelper\history`。从“文件 → 历史版本”或编辑器工具栏打开,可查看与当前内容的差异,再恢复到编辑区;恢复可撤销,只有再次保存才覆盖磁盘文件。历史版本属于本机,不随文档或配置导出。
图片可通过工具栏选择、从文件管理器拖入,或直接粘贴截图。程序自动复制到文档旁的“文档名.assets”文件夹,插入相对路径;相同图片复用资源。移动或分享文档时,请同时携带该资源文件夹。撤销图片插入不会删除已保存的图片资源。
点击“表格”可设置行列数、增删当前行列、调整列对齐,并通过“从 Excel 粘贴”转换复制的单元格。第一行为表头。光标位于普通 Markdown 表格中时编辑原表格;引用或列表中的嵌套表格仍请使用源码编辑。应用整个表格后可一次撤销。
图形表格最多支持 1000 行(含表头)、100 列。粘贴或编辑超限表格会明确提示,不截断内容;原表格保持不变。更大的表格请拆分,或通过源码编辑。
分屏的“同步滚动”按标题、段落和代码块对应位置双向同步,支持自动换行的源码与大图片。取消勾选后两侧独立滚动。同步只在编辑预览中按滚动事件运行,阅读窗口不增加持续扫描。
关闭同步滚动后,编辑引起的预览刷新也会保留预览原来的滚动位置。
编辑时左侧大纲可点击定位源码标题。预览刷新使用防抖机制,避免每次按键都重新渲染。
## 9. 样式管理
菜单栏 `样式` 用于管理文档展示样式:
- 可切换内置样式。
- 可创建自定义样式。
- 自定义样式可编辑、导出、导入和删除。
- 内置样式不可删除。
图形界面可设置不同对象的字体和段落格式,例如:
- 正文、一级到六级标题、引用、无序/有序/任务列表、代码块、表头文字和单元格文字。
- 加粗、强调、删除线、超链接、行内代码采用字符样式;可设置下划线、删除线和背景色,未设置的字体与字号继承所在段落。
- 表格基准可设置边框颜色、宽度、实线/虚线/无边框等样式和单元格内边距;列表可设置标记形式与嵌套层级缩进。
- 中文字体和英文字体分开设置。
- 字号支持磅(pt)、像素(px)和中文常用字号,例如五号 10.5 磅;可设置加粗、斜体、字体颜色和字符间距。
- 对齐支持左对齐、居中、右对齐和两端对齐。
- 行距支持单倍、1.5 倍、双倍、多倍、固定值和最小值。
- 段前 / 段后间距支持磅、字符(em)或行,可设置同样式段落间不添加间距。
- 左右缩进支持字符、磅或厘米;特殊缩进可选择无、首行或悬挂,首行与悬挂互斥。
- 分页支持与下段同页、段中不分页、段前分页和孤行控制。
“继承”沿用基准样式或文档默认值;数字 0 表示明确清零。复选框方块表示继承、勾选表示开启、空白表示关闭。设置窗口下方提供快速预览,“实际阅读效果”页使用阅读器显示完整示例;分页效果以 Word 为准。旧样式文件会自动兼容原有的像素字号、字符间距和缩进。
行内代码、表头和单元格的“兼容:代码基准 / 表格基准”表示沿用旧配置。显式选择“文档默认 / 所在段落”会解除该兼容继承;也可以重新选择兼容基准。仅修改名称不会解除原有继承。
### 样式面板与 Word 导出
打开“样式 → 样式面板”,可查看全部样式或当前文档已用样式。编辑 Markdown 时,面板提示光标所在段落及其中包含的字符样式。双击条目修改样式名称、同类型基准及格式;改变样式不会改写 Markdown 内容。基于内置样式修改时自动创建自定义样式集,并保留原内置样式的字体、行距等基础信息,导出 Word 和迁移样式文件后继续生效。
首行和悬挂缩进可选择字符、磅或像素;高级 CSS 中的绝对缩进保留原单位,不会因继承字号而改变。图形设置只写回实际改动的字段,未改动的高级 CSS 数值即使超出控件范围也会保留。
样式集是一整套格式方案,正文、标题和链接等是其中的单个样式。启用项目默认后,修改作用于当前项目;否则修改全局默认。原有样式文件、配置导入导出和项目模板继续可用。面板和实际阅读预览按需创建,不增加启动阶段的窗口或浏览器切换。
三个 Word 导出引擎均创建 `MDHelper 正文`、`MDHelper 标题 1`、`MDHelper 加粗` 等命名样式。导出后,在 Word 的样式面板中修改相应样式,即可统一调整引用该样式的内容;正文的字体和字号也会传递到未单独设置字体的加粗、强调和链接文字。表格边框及内边距通过 Word 表格样式修改。
Word 每段文字只能引用一个字符样式,因此加粗链接等组合会生成 `MDHelper 超链接+加粗` 等组合样式。不同嵌套顺序分别保存,按 Markdown 从外到内应用格式;含链接的组合以超链接为基准,内层明确设置可覆盖外层。组合不会同时继承多个字符样式,其他组合属性可通过对应组合样式统一修改。嵌套列表使用基于对应列表样式的层级样式,层级缩进可单独修改。
内层明确设置与基准的初始值相同时,也会保留该覆盖关系;之后修改基准不会改变内层的明确设置。列表的缩进由命名段落样式控制,编号只负责标记和序号,因此在 Word 样式面板调整首行、悬挂和左右缩进可以继续生效。
Markdown 表格明确指定的列对齐会保存为基于表头或单元格文字样式的派生样式,字体等格式继续继承。引用中的宽松列表保留引用格式,生成基于引用样式的“引用内段落”组合样式;其列表布局或其他独立覆盖可通过该组合样式统一调整。Word 一个段落样式只有一个基准,组合样式不会同时继承列表和引用两条基准链。
Word 的字符样式会把加粗、斜体和删除线作为与段落格式叠加的开关。导出采用强调保护:明确字符样式中的这些字形设置会固定在对应文字上,避免修改正文或标题样式时反向关闭强调。字体、字号、颜色、下划线和段落仍由命名样式统一控制;受保护的加粗、斜体和删除线不能仅通过 Word 字符样式关闭,可在 MDHelper 调整后重新导出,或在 Word 中清除对应文字的直接字形格式再使用其原生样式规则。
纸张宽度是全局阅读设置,内置样式不再写死正文宽度,会跟随纸张宽度变化。
### 图形设置与高级 CSS 双向同步
“高级 CSS”显示完整的自定义样式。修改图形设置时,只更新对应对象的核心属性;原有背景、边框、阴影、注释和其他对象的规则会保留。直接修改 CSS 后,停止输入约 0.35 秒即可回填到图形设置和预览;立即点击确定也会先同步再保存。CSS 未写完整或存在语法错误时,保留上一次有效设置并提示修正,避免把半成品保存为样式。
核心同步覆盖对象的常规选择器,例如 `p`、`.reader p`、`h1`、`.reader h1`、`strong`、`em`、`s`、`a`,以及程序生成的 `data-mdh-style` 语义选择器。可识别的属性包括字体、字号、颜色、字符间距、`text-decoration-line`、`background-color`、对齐、行距、缩进、四向间距、换行分页,以及 `border-color` / `border-width`、表格 `padding` 和 `list-style-type`。支持常见字体简写、间距简写和 `!important`;重置当前对象只清除其核心设置,保留扩展效果。
独立的 `th`、`td`、`pre` 设置分别对应表头、单元格和代码块,不会串用到其他对象。旧版生成的 `table, th, td` 和 `pre, code` 合并规则仍作为兼容基准,未单独设置的子样式继续继承。
普通 `p` 选择器也作用于引用和宽松列表中的段落,Word 会保留这些上下文格式;紧凑列表没有独立段落元素,不受该选择器影响。表头和单元格的段前、段后及左右间距作用于内部文字区域,表格内边距仍独立设置。明显无效的 CSS 值(例如 `font-size:nope`)会被忽略并提示,前面的有效声明继续同步;有效但不能转换为 Word 的扩展表达式仍保留为 CSS。
宽松列表中明确设置的 `p` 间距和缩进不会被列表辅助规则清零。图形设置修改引用等子对象时,会保留必要的 `!important` 优先级,使修改真正生效。无效的多值声明、错误单位和互斥文字修饰同样按浏览器的回退规则处理;`border-style:none` / `hidden` 会同步为 Word 无边框,改变宽度不会重新开启边框。
颜色选择“随所在文字颜色”(CSS `currentColor` / `inherit`)会继承段落或外层文字的颜色,不等同于“自动(随主题)”。如果它同时需要取消某个字符基准中的固定颜色,Word 无法只取消一个继承属性,因此导出会将该基准的其他已解析格式保留在当前命名字符样式内;导出后请修改此命名样式,其他普通样式的基准继承保持不变。
例如,将正文规则中的 `font-size: 12pt` 改成 `font-size: 14pt`,图形字号会变为 14 磅,导出 Word 也使用 14 磅。之后在图形界面调整字号,CSS 对应值会随之更新。删除某项属性后,如果没有其他常规规则提供该属性,图形设置显示“继承”。
中英文字体及 Word 特有设置使用可编辑的 CSS 自定义属性:`--mdhelper-font-chinese` / `--mdhelper-font-english` 区分字体;`--mdhelper-line-spacing-mode: at-least` 配合磅值 `line-height` 表示最小值行距;`--mdhelper-contextual-spacing: true` 表示同样式段落间不添加间距。这些属性由图形设置自动生成。
下划线和删除线分别使用 `--mdhelper-underline: true/false`、`--mdhelper-strike: true/false`,配合程序生成的 `text-decoration-line: var(--mdhelper-text-decoration, none)`。未指定的一项继续继承,修改另一项不会将它关闭。也可直接写标准 `text-decoration` / `text-decoration-line`,这时按 CSS 声明顺序、选择器优先级及 `!important` 解析整组文字修饰。
`@media`、嵌套规则、局部选择器(例如 `p:hover`、特定类名),以及图形界面无法表示的 `calc()`、动态变量、透明颜色等值会保留在 CSS 中,并在编辑器底部说明同步范围。它们不会被猜测为统一的图形设置或 Word 格式。需要统一控制文档核心排版时,建议修改程序生成的对象规则;扩展规则仍可用于阅读器及 HTML/PDF 的显示效果。
## 10. 媒体与表格
图片:
- 点击可打开灯箱。
- 支持放大、缩小、旋转、适应窗口、原始大小、保存图片、在文件夹中显示。
音频和视频:
- 支持内置预览。
- 对无法内置播放的格式,可选择系统播放器或记住指定程序。
表格:
- 宽表格支持横向滚动。
- 可一键复制为制表符分隔文本。
## 11. 自动刷新
默认开启自动刷新。推荐刷新延迟为 `1 秒`:
- 既能及时看到外部编辑器保存后的变化。
- 又能避免文件连续保存时频繁重渲染。
设置中可选择:
| 模式 | 说明 |
|---|---|
| 当前文档、资源和目录 | 当前文档、引用图片/媒体、文件树和搜索索引都更新。 |
| 当前文档和引用资源 | 更新当前文档和其引用资源。 |
| 仅当前文档 | 只刷新当前正在看的文件。 |
| 关闭 | 不自动刷新。 |
MDHelper 读取文档时不会独占文件,外部程序仍可修改文件。
## 12. 导出
当前文档可导出为:
- PDF
- HTML
- DOCX
- MHTML
MHTML 会等待图片、公式和 Mermaid 图表渲染完成,再将页面与样式、图片和本地字体封装到单文件中。导出时显示进度并支持取消;取消或失败不会覆盖已有输出。缺失图片、加载超时或无法封装的远程样式资源会提示失败,请先修复路径或改用本地资源。离线归档用于保存静态显示效果,音视频、外部链接及需要联网的交互内容不属于静态归档范围。
PDF 和 Word 共用导出页面设置:A4 / A3 / Letter、纵向或横向、四个方向页边距、目录开关及 1–6 级目录、页眉、页脚和页码。设置会自动记住。页眉或页脚启用时,对应页边距至少为 12 mm,避免遮挡正文。
PDF 使用白色纸张背景,按所选层级生成带真实页码的目录;启用目录时正文从新页面开始。Word 使用目录域,打开文件后如未自动生成目录,可右键目录提示文字并选择“更新域”;页码由 Word 的实际分页决定。
四种格式均导出当前编辑区内容,包括尚未保存的修改;导出不会代替保存源文件。导出开始后使用固定内容,切换标签不会改变正在导出的文档或图片路径。
导出前检查会提示缺失的本地图片/链接、远程图片依赖,以及当前 Word 导出方式对公式、多级列表、Mermaid、内嵌 HTML 和扩展 CSS 的限制。可返回编辑或继续导出核对。Word 和 PDF 的耗时生成阶段提供进度状态及取消;成功后才替换目标文件,失败或取消不会覆盖已有输出。
DOCX 导出可选择 `pandoc` 或 `python-docx` 相关实现。正式安装版已包含 Pandoc,无需用户另行下载或配置 PATH。导出的 HTML 与阅读页一样不包含阅读进度控件。
Pandoc、python-docx 和内置基础导出均保留图形设置中的字体、字号、颜色、字符间距、对齐、缩进、段间距、行距和分页选项。正文、各级标题、列表、引用、代码和表格分别应用对应设置;Markdown 中显式加粗、斜体的局部文本仍保留强调。Word 字号按其支持的半磅精度写入;自动颜色使用 Word 自动文字颜色。
高级 CSS 中可识别的核心属性会同步到图形设置,并用于 Word 导出;背景、边框、条件规则等扩展 CSS 不转换为 Word 格式。阅读器是连续页面,固定值/最小值行距及分页效果可能与 Word 显示不同;导出文件分别保留 Word 的固定值、最小值和分页属性。三个引擎的表格、复杂 Markdown、图片或公式支持范围仍按各自能力处理。
## 13. 配置与迁移
MDHelper 会保存:
- 最近文件和上次打开文件夹。
- 主题、背景、字号、滚轮速度、纸张宽度。
- 文档样式和自定义样式。
- 书签和滚动位置。
- 文件类型展示设置。
- 外部程序映射。
可通过配置导入/导出 JSON 在不同机器之间迁移。
## 14. 快捷键
| 快捷键 | 功能 |
|---|---|
| `Ctrl+O` | 打开文件夹或文件 |
| `Ctrl+P` | 导出 PDF |
| `Ctrl+D` | 添加书签 |
| `Ctrl+F` | 当前页查找 |
| `Ctrl+Shift+F` | 全文搜索 |
| `Ctrl+E` | 编辑当前 Markdown |
| `Ctrl+S` | 编辑模式保存 |
| `Ctrl+H` | 编辑模式查找替换 |
| `F5` | 刷新当前文档 |
## 15. 命令行检查
扫描文档中的本地链接和媒体资源:
```powershell
.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .
```
打包版:
```powershell
.\dist\MDHelper\MDHelper.exe --check --project-root .
```
# 0.4 新增工作流
- **恢复工作现场**:正常退出后,再次打开同一文件夹会恢复标签顺序、当前文档、编辑模式和分屏状态。后台标签在点击时加载;可在“文件 → 启动时恢复工作现场”中关闭。未保存草稿仍按原有方式提示恢复。
- **文档检查**:在“工具 → 检查文档链接与图片”中扫描当前项目,检查本地链接、图片和章节锚点。检查使用当前编辑内容,双击结果可定位 Markdown 编辑行或查看 HTML 源码。
- **安全重命名**:在文件树重命名时,若存在需要同步修改的引用,会显示差异预览。确认后统一保存这些修改,并更新标签、最近文件和书签。备份位于本地应用数据目录的 `MDHelper/rename-backups`。
- **保存冲突对比**:磁盘被其他程序修改或删除时,保存前展示两份内容。勾选差异段落采用磁盘版本,也可以编辑合并结果;取消会保留当前编辑内容。
- **批量与合并导出**:在“文件 → 批量与合并导出”中勾选 Markdown 文件,调整顺序并选择 Word/PDF。默认分别输出,也可勾选合并为一份文档。使用当前样式和编辑内容,全部转换成功后才保存输出。
- **项目样式与导出预设**:在“工具 → 项目样式与导出预设”中启用项目默认,或应用预设模板。启用后,在主窗口调整字体、段落和样式,会自动记入当前项目;页面参数与 Word/PDF 共用。模板可独立导入和导出,切换项目会恢复各自的设置。