Files
MDHelper/docs/troubleshooting.md
T

144 lines
5.0 KiB
Markdown
Raw Normal View History

2026-06-18 12:30:37 +08:00
# MDHelper 常见问题
2026-05-25 17:12:00 +08:00
## 找不到文档大纲
2026-05-25 17:12:00 +08:00
大纲已经移到左侧导航栏:
2026-05-25 17:12:00 +08:00
1. 点击左侧的 `大纲` 页签。
2. 点击标题即可跳转。
3. 如果列表为空,请确认当前文档包含 Markdown 标题,必要时刷新当前文档。
2026-05-25 17:12:00 +08:00
大纲不会跟随正文滚动选中当前章节,这是为了避免持续定位和界面同步。
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
## 每行文字太少或太多
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
打开 `工具 - 设置 - 纸张宽度`:
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
- 默认 `A4(x1)`:适合普通阅读。
- `A4 × 1.25` / `A4 × 1.5`:适合宽屏。
- `A4 × 1.75` / `A4 × 2`:适合代码、宽表格和技术文档。
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
纸张宽度只改变正文最大宽度,不改变字号。
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
## 滚动不够流畅
2026-05-25 17:12:00 +08:00
可尝试:
2026-06-18 12:30:37 +08:00
- 将鼠标滚轮速度保持在 `1.0` 附近。
- 对超大代码文件,避免同时启用过多文件类型。
- Mermaid、公式、大图片和超长代码块很多的文档会更依赖 WebEngine 渲染性能。
## 文件夹很大时卡顿
建议:
- 默认只展示 Markdown / 网页文件。
2026-06-22 18:07:34 +08:00
- 只在需要时启用 Python、C/C++ 或 Fortran。
2026-06-18 12:30:37 +08:00
- 避免把构建目录、依赖目录、虚拟环境目录作为阅读根目录。
- 使用左侧搜索定位目标文件。
MDHelper 会跳过超大代码文件的全文索引和部分高亮处理,以减少卡顿。
## 文件被外部修改后没有刷新
检查 `工具 - 设置 - 自动刷新`:
- 推荐选择 `当前文档、资源和目录`。
- 推荐刷新延迟为 `标准(1 秒)`。
- 若关闭自动刷新,需要手动点击刷新按钮或按 `F5`。
MDHelper 读取文档时不会锁定文件,外部编辑器仍可保存。
## 图片或媒体打不开
检查:
- Markdown 中的相对路径是否正确。
- 文件是否仍在原位置。
- 文件名大小写是否一致。
- 视频格式是否被 Qt 内置播放器支持。
对不支持的媒体格式,可选择用系统默认程序打开,也可以记住指定播放器。
## DOCX 导出失败
检查:
- 是否安装 python-docx。
- 当前文档路径和输出目录是否可写。
- 文档中引用的图片路径是否存在。
正式安装版 MDHelper 已包含 Pandoc,无需用户安装或配置 PATH。如果提示“未找到程序内置的 Pandoc”,说明程序文件可能不完整,请重新获取完整版本。也可临时切换到 python-docx 或内置基础导出;复杂 Markdown 的 DOCX 版式通常 Pandoc 更稳定。
2026-06-18 12:30:37 +08:00
## PDF 导出失败
检查:
- 当前文档是否能正常阅读。
- 输出路径是否可写。
- 文件名是否包含系统不允许的字符。
- WebEngine 是否已完成页面加载。
可先导出 HTML,确认内容渲染正常,再导出 PDF。
## 导出的 Word 目录仍显示提示文字
Word 目录使用可更新的目录域。打开文件后,在目录提示文字处右键选择“更新域”,由 Word 按实际页面生成页码。PDF 的目录页码在导出时自动生成。
## 修改已经保存,想恢复旧内容
使用“文件 → 历史版本”,查看版本差异后恢复到编辑区。确认无误再保存;恢复操作本身可以撤销。本机每个文件路径保留最近 20 个保存前版本,重命名后的路径有独立记录。
## 分享文档后图片无法显示
粘贴或拖入的图片保存在文档旁的“文档名.assets”文件夹。移动或分享 Markdown 时,请将该文件夹一起带走,并保持相对位置不变。
2026-06-18 12:30:37 +08:00
## 代码文件不显示
打开 `工具 - 设置 - 展示文件类型`,勾选需要的类型:
- Python
- C / C++
2026-06-22 18:07:34 +08:00
- Fortran
2026-06-18 12:30:37 +08:00
设置后文件树、搜索索引和自动刷新监听会随之更新。
## 设置后没有变化
多数设置会立即刷新当前文档。若仍未变化:
1. 按 `F5` 刷新。
2. 切换标签页再切回。
3. 关闭旧 exe,重新启动最新版本。
## 打包版提示缺少 PySide6
说明 PyInstaller 打包时没有正确带上 PySide6 或 WebEngine 资源。请使用项目根目录下的 `MDHelper.spec` 打包:
```powershell
.\pack\_installer.cmd
2026-05-25 17:12:00 +08:00
```
2026-06-18 12:30:37 +08:00
打包后执行:
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
```powershell
.\dist\MDHelper\MDHelper.exe --check --project-root .
2026-06-18 12:30:37 +08:00
```
2026-05-25 17:12:00 +08:00
## 另存为失败或图片无法复制
另存为到其他目录会同时复制相对引用的图片。请确认源图片存在且目标目录可写。失败时编辑内容、原文档路径和草稿仍保留;只有全部保存成功才切换到新路径。
## 从 Excel 粘贴表格提示超限
图形表格上限为 1000 行(含表头)、100 列。超限时不导入任何单元格,以免静默截断。可拆分后粘贴,或直接编辑 Markdown 源码。
## MHTML 导出失败
离线归档需要先加载文档中的实际图片、公式及图表。请根据提示修复资源路径,或将未能封装的远程样式资源改为本地资源。取消和失败均保留原有输出文件。成功导出的归档可单独移动,不需要原图片目录。
2026-06-18 12:30:37 +08:00
## 如何定位日志
2026-05-25 17:12:00 +08:00
2026-06-18 12:30:37 +08:00
MDHelper 会把日志写到用户可写目录。若启动或打开文档异常,优先查看最近的运行日志,并把错误堆栈和打开的文件路径一起记录下来。
2026-06-22 18:07:34 +08:00