126 lines
3.6 KiB
Markdown
126 lines
3.6 KiB
Markdown
# MDHelper 常见问题
|
||
|
||
## 右侧外部目录栏还显示
|
||
|
||
默认推荐使用网页内文档大纲,位置在正文右侧。若仍看到最右侧 Qt 目录栏,请检查:
|
||
|
||
1. 打开 `工具 - 设置`。
|
||
2. 勾选 `网页内大纲`。
|
||
3. 取消或禁用 `外部目录栏`。
|
||
4. 刷新当前文档。
|
||
|
||
当网页内大纲开启时,外部目录栏会自动隐藏。
|
||
|
||
## 文档大纲在正文左侧
|
||
|
||
0.2.0 当前布局应为正文在左、大纲在正文右侧。如果仍在左侧,说明正在运行旧 exe 或旧源码。请重新运行最新源码,或重新打包 exe。
|
||
|
||
## 每行文字太少或太多
|
||
|
||
打开 `工具 - 设置 - 纸张宽度`:
|
||
|
||
- 默认 `A4(x1)`:适合普通阅读。
|
||
- `A4 × 1.25` / `A4 × 1.5`:适合宽屏。
|
||
- `A4 × 1.75` / `A4 × 2`:适合代码、宽表格和技术文档。
|
||
|
||
纸张宽度只改变正文最大宽度,不改变字号。
|
||
|
||
## 滚动不够流畅
|
||
|
||
可尝试:
|
||
|
||
- 使用网页内大纲和网页内进度条。
|
||
- 关闭外部目录栏。
|
||
- 将鼠标滚轮速度保持在 `1.0` 附近。
|
||
- 对超大代码文件,避免同时启用过多文件类型。
|
||
- Mermaid、公式、大图片和超长代码块很多的文档会更依赖 WebEngine 渲染性能。
|
||
|
||
## 文件夹很大时卡顿
|
||
|
||
建议:
|
||
|
||
- 默认只展示 Markdown / 网页文件。
|
||
- 只在需要时启用 Python 或 C/C++。
|
||
- 避免把构建目录、依赖目录、虚拟环境目录作为阅读根目录。
|
||
- 使用左侧搜索定位目标文件。
|
||
|
||
MDHelper 会跳过超大代码文件的全文索引和部分高亮处理,以减少卡顿。
|
||
|
||
## 文件被外部修改后没有刷新
|
||
|
||
检查 `工具 - 设置 - 自动刷新`:
|
||
|
||
- 推荐选择 `当前文档、资源和目录`。
|
||
- 推荐刷新延迟为 `标准(1 秒)`。
|
||
- 若关闭自动刷新,需要手动点击刷新按钮或按 `F5`。
|
||
|
||
MDHelper 读取文档时不会锁定文件,外部编辑器仍可保存。
|
||
|
||
## 图片或媒体打不开
|
||
|
||
检查:
|
||
|
||
- Markdown 中的相对路径是否正确。
|
||
- 文件是否仍在原位置。
|
||
- 文件名大小写是否一致。
|
||
- 视频格式是否被 Qt 内置播放器支持。
|
||
|
||
对不支持的媒体格式,可选择用系统默认程序打开,也可以记住指定播放器。
|
||
|
||
## DOCX 导出失败
|
||
|
||
检查:
|
||
|
||
- 是否安装 pandoc。
|
||
- 是否安装 python-docx。
|
||
- 当前文档路径和输出目录是否可写。
|
||
- 文档中引用的图片路径是否存在。
|
||
|
||
如果 pandoc 不可用,可切换到 python-docx 相关实现;复杂 Markdown 的 DOCX 版式通常 pandoc 更稳定。
|
||
|
||
## PDF 导出失败
|
||
|
||
检查:
|
||
|
||
- 当前文档是否能正常阅读。
|
||
- 输出路径是否可写。
|
||
- 文件名是否包含系统不允许的字符。
|
||
- WebEngine 是否已完成页面加载。
|
||
|
||
可先导出 HTML,确认内容渲染正常,再导出 PDF。
|
||
|
||
## 代码文件不显示
|
||
|
||
打开 `工具 - 设置 - 展示文件类型`,勾选需要的类型:
|
||
|
||
- Python
|
||
- C / C++
|
||
|
||
设置后文件树、搜索索引和自动刷新监听会随之更新。
|
||
|
||
## 设置后没有变化
|
||
|
||
多数设置会立即刷新当前文档。若仍未变化:
|
||
|
||
1. 按 `F5` 刷新。
|
||
2. 切换标签页再切回。
|
||
3. 关闭旧 exe,重新启动最新版本。
|
||
|
||
## 打包版提示缺少 PySide6
|
||
|
||
说明 PyInstaller 打包时没有正确带上 PySide6 或 WebEngine 资源。请使用项目根目录下的 `MDHelper.spec` 打包:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe -m PyInstaller .\MDHelper.spec --noconfirm --clean
|
||
```
|
||
|
||
打包后执行:
|
||
|
||
```powershell
|
||
.\dist\MDHelper.exe --check --project-root .
|
||
```
|
||
|
||
## 如何定位日志
|
||
|
||
MDHelper 会把日志写到用户可写目录。若启动或打开文档异常,优先查看最近的运行日志,并把错误堆栈和打开的文件路径一起记录下来。
|