21 KiB
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. 启动与打开文件
直接启动:
.\mdhelper_env\Scripts\python.exe -m mdhelper
启动时打开指定文件夹或文件:
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject
.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
打包版可以同样接收路径参数:
.\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 的字符样式会把加粗、斜体和删除线作为与段落格式叠加的开关。导出采用强调保护:明确字符样式中的这些字形设置会固定在对应文字上,避免修改正文或标题样式时反向关闭强调。字体、字号、颜色、下划线和段落仍由命名样式统一控制;受保护的加粗、斜体和删除线不能仅通过 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;重置当前对象只清除其核心设置,保留扩展效果。
例如,将正文规则中的 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. 导出
当前文档可导出为:
- 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. 命令行检查
扫描文档中的本地链接和媒体资源:
.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .
打包版:
.\dist\MDHelper\MDHelper.exe --check --project-root .
0.4 新增工作流
- 恢复工作现场:正常退出后,再次打开同一文件夹会恢复标签顺序、当前文档、编辑模式和分屏状态。后台标签在点击时加载;可在“文件 → 启动时恢复工作现场”中关闭。未保存草稿仍按原有方式提示恢复。
- 文档检查:在“工具 → 检查文档链接与图片”中扫描当前项目,检查本地链接、图片和章节锚点。检查使用当前编辑内容,双击结果可定位 Markdown 编辑行或查看 HTML 源码。
- 安全重命名:在文件树重命名时,若存在需要同步修改的引用,会显示差异预览。确认后统一保存这些修改,并更新标签、最近文件和书签。备份位于本地应用数据目录的
MDHelper/rename-backups。 - 保存冲突对比:磁盘被其他程序修改或删除时,保存前展示两份内容。勾选差异段落采用磁盘版本,也可以编辑合并结果;取消会保留当前编辑内容。
- 批量与合并导出:在“文件 → 批量与合并导出”中勾选 Markdown 文件,调整顺序并选择 Word/PDF。默认分别输出,也可勾选合并为一份文档。使用当前样式和编辑内容,全部转换成功后才保存输出。
- 项目样式与导出预设:在“工具 → 项目样式与导出预设”中启用项目默认,或应用预设模板。启用后,在主窗口调整字体、段落和样式,会自动记入当前项目;页面参数与 Word/PDF 共用。模板可独立导入和导出,切换项目会恢复各自的设置。