reStructuredText插件装不上，先确认拼写为reStructuredText而非rst等变体，再检查安装路径、权限及Python解释器配置；需确保sphinx-build可用、index.rst存在且含toctree指令，并避免中文路径。
reStructuredText 插件装不上？先确认拼写和安装路径
插件名是 reStructuredText，不是 rst、rest 或 rst-plugin——Package Control 里搜错一个字母就找不到。按 Ctrl+Shift+P → 输入 Package Control: Install Package → 回车 → 精确输入 reStructuredText → 选中安装。
装完打开任意 .rst 文件，右下角状态栏应显示 reStructuredText；若仍是 Plain Text，手动点击状态栏切换语法类型。
常见失败点：
- Sublime Text 3 的
Packages/User目录权限被系统锁定（尤其 Windows 上以 Administrator 安装过），导致插件无法写入配置 - 插件安装后未重启 Sublime（极少数情况需重启才生效）
- 已安装同名但非官方插件（如旧版
RST），冲突覆盖
Python 解释器路径没配对，预览直接静默失败
插件默认调用系统 python 命令，但如果你用的是 Anaconda、pyenv 或虚拟环境，必须显式指定解释器路径，否则 sphinx-build 找不到依赖、报错不明确。
进 Preferences → Package Settings → reStructuredText → Settings – User，填入：
{"python_binary": "C:/Users/xxx/Anaconda3/python.exe"}
注意：
- Windows 路径用正斜杠
/或双反斜杠\，单反斜杠会解析失败 - 路径必须指向真实存在的
python.exe，不是pythonw.exe（后者无 stdout，插件收不到构建日志） - Mac/Linux 用户若用 pyenv，路径类似
/Users/xxx/.pyenv/versions/3.11.9/bin/python
Ctrl+Shift+R 没反应？检查 sphinx-build 是否可用
插件的预览功能本质是调用命令行工具，不是内置服务。按下 Ctrl+Shift+R 后没反应，90% 是因为 sphinx-build 命令根本不可达。
先在终端执行：
sphinx-build --version
如果报 'sphinx-build' is not recognized 或 command not found，说明 Sphinx 没装或没进 PATH。
解决方式：
- 全局安装：
pip install sphinx（不要只装docutils，它不支持:math:、自定义角色等核心特性） - 确保安装后
sphinx-build在 PATH 中：Windows 查Scripts/目录，macOS/Linux 查bin/目录 - Sublime 控制台（
Ctrl+`）里能看到完整错误，例如[Errno 2] No such file or directory: 'sphinx-build'，这就是路径问题
生成 HTML 是空的？index.rst 和 toctree 是硬性门槛
Sphinx 不是“读目录下所有 .rst 就构建”，它严格依赖 index.rst + toctree 指令启动扫描。没有它，sphinx-build -b html source build 会输出 WARNING: no files found，但页面仍能打开——只是空的。
必须满足：
-
source/index.rst文件存在，且编码为UTF-8 without BOM（Sublime 右下角点击编码名 → 选UTF-8） -
index.rst至少含一个.. toctree::指令，哪怕只列自己：.. toctree:: :maxdepth: 1 index
- 新增的
chapter1.rst必须被加进某个toctree里，否则 Sphinx 完全忽略该文件
容易被忽略的细节：Sphinx 对中文路径极度敏感。如果项目路径含中文（如 C:/我的文档/wiki），sphinx-build 可能中途退出且无报错——把整个项目移到纯英文路径下再试。
