255 lines
12 KiB
Markdown
255 lines
12 KiB
Markdown
# MDHelper 用户手册
|
||
|
||
MDHelper 是一个本地 Markdown / 代码文档阅读器,适合阅读项目说明、技术手册、源码旁文档和离线帮助文件。它使用 PySide6 提供桌面窗口,用 Qt WebEngine 渲染 Markdown 转换后的 HTML 页面,并在本地完成全文搜索、样式管理、导出和自动刷新。
|
||
|
||
当前版本:`0.2.3`
|
||
|
||
## 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` 保存。
|
||
- 另存为。
|
||
- 自动保存草稿和恢复草稿。
|
||
- 保存前检测磁盘文件是否被外部程序修改,避免覆盖外部编辑。
|
||
|
||
编辑时左侧大纲可点击定位源码标题。预览刷新使用防抖机制,避免每次按键都重新渲染。
|
||
|
||
## 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
|
||
|
||
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 .
|
||
```
|
||
|