Sublime Text 中需手动安装 Ruby 和 asciidoctor gem 并确保 PATH 正确，推荐终端启动 subl 继承环境变量；HTML 预览需指定样式或内联 CSS；中文文档须设 :lang: zh-CN 等属性；关闭自动构建更稳定，注意编码为 UTF-8（无 BOM）。
Sublime Text 里怎么让 asciidoctor 命令真正跑起来
默认安装完 Asciidoctor 插件，asciidoctor 命令找不到——根本原因是插件不自带 Ruby 环境和 asciidoctor gem，它只调用系统 PATH 里的可执行文件。
实操建议：
- 先在终端运行
which asciidoctor，确认命令路径；如果返回空，说明没装或没加进 PATH - Mac 用户用
brew install ruby后，再gem install asciidoctor；Windows 用户推荐用RubyInstaller（带 DevKit），然后gem install asciidoctor - Sublime Text 启动方式影响 PATH：直接双击图标启动时，PATH 可能不含 shell 配置的路径；改用终端执行
subl启动，才能继承 shell 的环境变量 - 实在不行，可在插件配置里硬编码路径，比如
"asciidoctor_command": "/usr/local/bin/asciidoctor"
预览 HTML 时样式丢失或显示空白
Asciidoctor 默认输出纯 HTML，不带 CSS；插件调用 asciidoctor 时若没指定 backend 或 theme，浏览器打开后就是没样式的白页。
实操建议：
- 确保文档开头有
:doctype: article和:stylesheet: ./css/default.css（路径需相对于当前 adoc 文件） - 更稳妥的做法是用
-a stylesheet=参数强制内联样式："asciidoctor_flags": ["-a", "stylesheet="]，这样生成的 HTML 自带基础 CSS - 如果用了自定义主题（如
asciidoctor-pdf或asciidoctor-fopub），它们不参与 HTML 预览流程，别混淆 backend - 检查浏览器控制台是否报
Failed to load resource——大概率是 CSS 路径错或服务器没起本地服务（Sublime 插件默认用 file:// 协议，部分 CSS 特性会被禁用）
中文乱码、标点不换行、目录不生成
Asciidoctor 默认按英文排版习惯处理，中文文档会出三类典型问题：文字挤成一团、顿号逗号后不断行、toc::[] 不渲染。
实操建议：
- 必须加
:lang: zh-CN和:stem: latexmath（如需数学公式），否则中文字体 fallback 失败，且部分扩展（如 math）不激活 - 启用自动断行：加
:text_align: justify+:hardbreaks:（慎用）或更推荐:rouge-style: github（影响代码块，但间接改善整体排版流） -
toc::[]生效前提：文档要有至少两个=级标题，且插件配置里"toc": true开启；另外:toc: macro是旧写法，新版本推荐:toc:（值为left/right/preamble） - 导出 PDF 时中文仍乱码？那是
asciidoctor-pdf的事，和 Sublime 插件无关；需单独配pdf-theme并指定 Noto Sans CJK 字体路径
保存即构建太频繁，或热重载不生效
很多插件提供 “on_save” 自动构建，但 Asciidoctor 解析成本不低，频繁触发反而卡住编辑器；而所谓“实时预览”，其实只是监听文件变化并 reload 浏览器，不是真正的热重载。
实操建议：
- 关闭自动构建：
"auto_build_on_save": false，改用手动快捷键（默认Ctrl+Shift+A）更可控 - 想接近实时效果？用
asciidoctor --watch在终端单独起服务（需asciidoctor-livereloadgem），再配浏览器 LiveReload 插件；Sublime 插件本身不实现 WebSocket 通信 - 注意文件编码：Sublime 默认用 UTF-8 with BOM 保存，而
asciidoctor会报invalid byte sequence in UTF-8；务必设为UTF-8（无 BOM），菜单 → File → Save with Encoding → UTF-8 - 修改了
.adoc但预览没变？清浏览器缓存，或改用隐身窗口测试；部分插件生成的临时 HTML 文件名带时间戳，但浏览器可能仍缓存旧版本
最常被忽略的是环境隔离：系统 Ruby、rbenv、RVM、asdf 各自管理的 gem 目录互不相通，asciidoctor 装在哪，Sublime 就得用哪个。别在 zsh 里装好了就以为 GUI 应用能自动感知。
