# MDHelper 用户手册 MDHelper 是一个本地 Markdown / 代码文档阅读器,适合阅读项目说明、技术手册、源码旁文档和离线帮助文件。它使用 PySide6 提供桌面窗口,用 Qt WebEngine 渲染 Markdown 转换后的 HTML 页面,并在本地完成全文搜索、样式管理、导出和自动刷新。 当前版本:`0.2.0` ## 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.exe D:\CODE\SomeProject ``` MDHelper 支持同时运行多个程序窗口。不同窗口可以打开不同文件夹,标签页、搜索、设置和自动刷新状态互不影响。 ## 3. 主界面 界面主要分为三部分: | 区域 | 功能 | |---|---| | 左侧文档栏 | 打开文件夹、刷新、搜索、文件树、文件类型过滤结果。 | | 中间标签页 | 阅读、编辑、预览、媒体页面和欢迎页。 | | 文档内容右侧 | 网页内文档大纲,随正文滚动高亮当前章节。 | 默认阅读模式会把文档大纲和阅读进度放在网页内部,减少 Qt 控件同步,让滚动更接近浏览器网页。右侧旧 Qt 目录栏默认关闭;只有在设置中关闭网页内大纲并启用外部目录栏时才显示。 ## 4. 阅读 Markdown Markdown 支持: - 标题、段落、列表、引用、表格、任务列表。 - 提示块:`note`、`tip`、`important`、`warning`、`caution`。 - 代码块高亮、行号、复制、展开/收起。 - Mermaid 图表。 - KaTeX 或 MathJax 数学公式。 - 本地图片、GIF、音频和视频。 - 本地链接跳转和外部链接打开。 阅读页内的文档大纲位于正文右侧,点击章节可跳转。窄窗口下大纲会自动折叠或隐藏。 右下角阅读进度条会跟随主题改变颜色。进度条只在网页内部更新,Python 端只低频保存滚动位置。 ## 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、公式。 - `Ctrl+S` 保存。 - 另存为。 - 自动保存草稿和恢复草稿。 - 保存前检测磁盘文件是否被外部程序修改,避免覆盖外部编辑。 编辑预览中的网页内大纲可点击定位源码标题。预览刷新使用防抖机制,避免每次按键都重新渲染。 ## 9. 样式管理 菜单栏 `样式` 用于管理文档展示样式: - 可切换内置样式。 - 可创建自定义样式。 - 自定义样式可编辑、导出、导入和删除。 - 内置样式不可删除。 图形界面可设置不同对象的字体和段落格式,例如: - 正文段落、一级到六级标题、列表项、引用、代码块、表格。 - 中文字体和英文字体分开设置。 - 字号、加粗、斜体。 - 行间距:倍数或磅。 - 段前 / 段后间距:倍数或磅。 - 首行缩进和悬挂缩进:按字符设置。 纸张宽度是全局阅读设置,内置样式不再写死正文宽度,会跟随纸张宽度变化。 ## 10. 媒体与表格 图片: - 点击可打开灯箱。 - 支持放大、缩小、旋转、适应窗口、原始大小、保存图片、在文件夹中显示。 音频和视频: - 支持内置预览。 - 对无法内置播放的格式,可选择系统播放器或记住指定程序。 表格: - 宽表格支持横向滚动。 - 可一键复制为制表符分隔文本。 ## 11. 自动刷新 默认开启自动刷新。推荐刷新延迟为 `1 秒`: - 既能及时看到外部编辑器保存后的变化。 - 又能避免文件连续保存时频繁重渲染。 设置中可选择: | 模式 | 说明 | |---|---| | 当前文档、资源和目录 | 当前文档、引用图片/媒体、文件树和搜索索引都更新。 | | 当前文档和引用资源 | 更新当前文档和其引用资源。 | | 仅当前文档 | 只刷新当前正在看的文件。 | | 关闭 | 不自动刷新。 | MDHelper 读取文档时不会独占文件,外部程序仍可修改文件。 ## 12. 导出 当前文档可导出为: - PDF - HTML - DOCX - MHTML DOCX 导出可选择 `pandoc` 或 `python-docx` 相关实现。导出的 HTML 默认不包含网页内阅读进度条,避免把阅读状态写进文档。 ## 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.exe --check --project-root . ```