Files
MDHelper/docs/user_manual.md
T
shen 8dae91c2ca fix: protect editor content and harden document exports
Protect pending edits on window close, keep save-as paths and drafts consistent,
copy relative image resources, reject oversized table imports without truncation,
and preserve independent preview scrolling during refresh.

Archive rendered MHTML resources with portable references and embedded local
fonts. Preserve existing outputs on export cancellation or failure. Convert
editor match positions and filter directory results in linear passes.

Include the previously completed editor image/table/history improvements,
undoable replacement, export snapshots, shared page settings, and cancellable
PDF/Word export workflow. Update documentation and version to 0.3.1.

Validation: 142 pytest cases passed; GUI smoke, improvements integration, and
offline MHTML/scroll reliability smoke checks passed.
2026-10-29 18:22:42 +08:00

16 KiB
Raw Blame History

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 为准。旧样式文件会自动兼容原有的像素字号、字符间距和缩进。

纸张宽度是全局阅读设置,内置样式不再写死正文宽度,会跟随纸张宽度变化。

图形设置与高级 CSS 双向同步

“高级 CSS”显示完整的自定义样式。修改图形设置时,只更新对应对象的核心属性;原有背景、边框、阴影、注释和其他对象的规则会保留。直接修改 CSS 后,停止输入约 0.35 秒即可回填到图形设置和预览;立即点击确定也会先同步再保存。CSS 未写完整或存在语法错误时,保留上一次有效设置并提示修正,避免把半成品保存为样式。

核心同步覆盖对象的常规选择器,例如 p、.reader p、h1、.reader h1,以及程序生成的正文、列表、引用、代码和表格选择器。可识别的属性包括 font-family、font-size、font-weight、font-style、color、letter-spacing、text-align、line-height、text-indent、margin/四个方向的间距,以及换行、分页属性。支持常见字体简写、间距简写和 !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 表示同样式段落间不添加间距。这些属性由图形设置自动生成。

@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. 命令行检查

扫描文档中的本地链接和媒体资源:

.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .

打包版:

.\dist\MDHelper\MDHelper.exe --check --project-root .