必须安装AsciiDocPlus插件（作者joaopev）并手动绑定.adoc文件语法为AsciiDocPlus，否则文件显示Plain Text；需配置asciidoctor_path路径并从终端启动Sublime以确保PATH继承，缺一不可。
AsciiDocPlus 插件必须装，且只兼容 Sublime Text 4
Sublime Text 默认不识别 .adoc 文件，装错插件或版本不匹配，右下角永远显示 Plain Text。不是“没生效”，是根本没加载语法定义。
必须安装 AsciiDocPlus（作者 joaopev），不是 AsciiDoc（maze-for-ascii）或 asciidoctor_js。后者在 ST4 下已停止维护，且不支持源码块语言高亮、文档属性（如 :toc:）等关键功能。
- 用
Ctrl+Shift+P→Package Control: Install Package→ 搜索AsciiDocPlus，认准作者名 - 装完重启 Sublime Text；若控制台报
ImportError，说明 Package Control 版本过旧，需先升级 - 打开任意
.adoc文件，右下角点击语法名 →Open all with current extension as…→ 选AsciiDocPlus→AsciiDocPlus（注意不是AsciiDoc）
右下角选错语法 = 高亮全失效
很多人点了 AsciiDoc 就以为搞定了，但 AsciiDocPlus 和 AsciiDoc 是两个独立语法包，作用域（scope）完全不同。选错一个，**bold**、= Title、[source,java] 全部灰底黑字。
- 验证是否生效：输入
= Document Title，标题行应变蓝；输入**text**，星号和文字应不同色 - 右键 →
Developer → Show Scope Name，光标停在标题上，应显示heading.1.asciidocplus；若显示source.plain，说明绑定失败 - 如果菜单里没出现
AsciiDocPlus，关掉文件，再用View → Syntax → Open all with current extension as…手动指定
预览 HTML 需要本地 asciidoctor 可执行文件
AsciiDocPlus 不带渲染能力，它只管高亮。想点快捷键预览 HTML，必须让插件找到系统里的 asciidoctor 命令——不是 gem，是可执行文件路径。
- 终端运行
which asciidoctor（macOS/Linux）或where asciidoctor（Windows），记下输出路径 - 打开
Preferences → Package Settings → AsciiDocPlus → Settings，填入"asciidoctor_path": "/usr/local/bin/asciidoctor"或"C:\Ruby31-x64\bin\asciidoctor.bat" - 别依赖
asciidoctor_js回退机制：它在 ST4 下常卡死或输出空白页，关闭它更稳定 - 中文文档务必加
:lang: zh-CN到文档开头，否则生成的 HTML 会缺字体声明
编码与环境变量是隐藏杀手
即使语法和路径都对，预览仍失败，大概率是 Sublime 启动时没继承 shell 的 PATH，或文件用了 BOM 编码。
- 推荐从终端启动：
subl .（macOS/Linux）或subl（Windows PowerShell），确保 Ruby 和asciidoctor在 PATH 中 - 右下角点击编码名 → 选
UTF-8（不是UTF-8 with BOM），含中文的.adoc文件一旦带 BOM，属性解析会中断 - 插件设置里禁用
"auto_build": true，手动触发预览更可控；自动构建常因并发冲突导致 PDF 输出乱码
AsciiDocPlus 语法没手动绑定、asciidoctor_path 没填对、或者 Sublime 没从终端启动——这三处漏掉任何一环，整个流程就停在灰色文字上。 
