Files
MDHelper/docs/troubleshooting.md
T

3.5 KiB
Raw Blame History

MDHelper 常见问题

找不到文档大纲

大纲已经移到左侧导航栏:

  1. 点击左侧的 大纲 页签。
  2. 点击标题即可跳转。
  3. 如果列表为空,请确认当前文档包含 Markdown 标题,必要时刷新当前文档。

大纲不会跟随正文滚动选中当前章节,这是为了避免持续定位和界面同步。

每行文字太少或太多

打开 工具 - 设置 - 纸张宽度:

  • 默认 A4(x1):适合普通阅读。
  • A4 × 1.25 / A4 × 1.5:适合宽屏。
  • A4 × 1.75 / A4 × 2:适合代码、宽表格和技术文档。

纸张宽度只改变正文最大宽度,不改变字号。

滚动不够流畅

可尝试:

  • 将鼠标滚轮速度保持在 1.0 附近。
  • 对超大代码文件,避免同时启用过多文件类型。
  • Mermaid、公式、大图片和超长代码块很多的文档会更依赖 WebEngine 渲染性能。

文件夹很大时卡顿

建议:

  • 默认只展示 Markdown / 网页文件。
  • 只在需要时启用 Python、C/C++ 或 Fortran。
  • 避免把构建目录、依赖目录、虚拟环境目录作为阅读根目录。
  • 使用左侧搜索定位目标文件。

MDHelper 会跳过超大代码文件的全文索引和部分高亮处理,以减少卡顿。

文件被外部修改后没有刷新

检查 工具 - 设置 - 自动刷新:

  • 推荐选择 当前文档、资源和目录。
  • 推荐刷新延迟为 标准(1 秒)。
  • 若关闭自动刷新,需要手动点击刷新按钮或按 F5。

MDHelper 读取文档时不会锁定文件,外部编辑器仍可保存。

图片或媒体打不开

检查:

  • Markdown 中的相对路径是否正确。
  • 文件是否仍在原位置。
  • 文件名大小写是否一致。
  • 视频格式是否被 Qt 内置播放器支持。

对不支持的媒体格式,可选择用系统默认程序打开,也可以记住指定播放器。

DOCX 导出失败

检查:

  • 是否安装 python-docx。
  • 当前文档路径和输出目录是否可写。
  • 文档中引用的图片路径是否存在。

正式安装版 MDHelper 已包含 Pandoc,无需用户安装或配置 PATH。如果提示“未找到程序内置的 Pandoc”,说明程序文件可能不完整,请重新获取完整版本。也可临时切换到 python-docx 或内置基础导出;复杂 Markdown 的 DOCX 版式通常 Pandoc 更稳定。

PDF 导出失败

检查:

  • 当前文档是否能正常阅读。
  • 输出路径是否可写。
  • 文件名是否包含系统不允许的字符。
  • WebEngine 是否已完成页面加载。

可先导出 HTML,确认内容渲染正常,再导出 PDF。

代码文件不显示

打开 工具 - 设置 - 展示文件类型,勾选需要的类型:

  • Python
  • C / C++
  • Fortran

设置后文件树、搜索索引和自动刷新监听会随之更新。

设置后没有变化

多数设置会立即刷新当前文档。若仍未变化:

  1. 按 F5 刷新。
  2. 切换标签页再切回。
  3. 关闭旧 exe,重新启动最新版本。

打包版提示缺少 PySide6

说明 PyInstaller 打包时没有正确带上 PySide6 或 WebEngine 资源。请使用项目根目录下的 MDHelper.spec 打包:

.\pack\_installer.cmd

打包后执行:

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

如何定位日志

MDHelper 会把日志写到用户可写目录。若启动或打开文档异常,优先查看最近的运行日志,并把错误堆栈和打开的文件路径一起记录下来。