sublime text 无法直接调用 asciidoctor-pdf 生成 pdf，需手动运行命令行；必须安装 asciidocplus 插件并正确设置语法高亮，配置 ruby 环境、字体路径及主题文件才能稳定输出中文 pdf。
Sublime Text 本身不支持直接调用 asciidoctor-pdf 生成 PDF，所有“一键导出”方案都依赖外部命令链；真正稳定可用的路径是：用 Sublime 编辑 .adoc 文件 → 手动运行 asciidoctor-pdf 命令 → 输出 PDF。中间环节若缺失 Ruby 环境、主题配置或字体声明，PDF 很可能空白、乱码或无样式。
Sublime 中正确识别和预览 AsciiDoc 文件
文件显示为 “Plain Text” 或无法高亮，基本等于后续流程全部失效。关键不是装插件，而是让 Sublime 知道这个文件该用什么规则解析。
- 必须安装
AsciiDocPlus插件（非AsciiDoc或asciidoctor_js），且仅兼容 Sublime Text 4；Package Control 搜索时注意作者名是joaopev - 打开任意
.adoc文件后，右下角点击语法名称 → 选择AsciiDocPlus（不是 AsciiDoc）→ 此时加粗**text**、标题= Title才会实时高亮 - 如需预览 HTML 效果，需关闭
asciidoctor_js回退机制，并在插件设置中填入本地asciidoctor可执行路径，例如：/usr/local/bin/asciidoctor（macOS）或C:\Ruby31-x64\bin\asciidoctor.bat（Windows）
从 .adoc 到 PDF：绕不开的 asciidoctor-pdf 命令行
Sublime 没有内置 PDF 渲染引擎，asciidoctor-pdf 是 Ruby 工具，必须独立安装并确保在终端可用。它不读取 Sublime 的配色方案，只认 AsciiDoc 语义和 YAML 主题。
- 先确认 Ruby 环境：终端运行
ruby -v和gem list asciidoctor-pdf；若未安装，执行gem install asciidoctor-pdf - 基础转换命令：
asciidoctor-pdf -o output.pdf input.adoc；默认输出使用 Helvetica 字体，中文会显示为方块 - 中文支持必须显式指定字体：添加
-a pdf-fontsdir=fonts/并确保fonts/目录下有NotoSansCJKsc-Regular.ttf（推荐）或simhei.ttf；同时在文档开头声明：:pdf-theme: chinese - 主题文件（如
chinese.yml）需包含：font_catalog:下定义中文字体别名，以及base_font_family: Noto Sans CJK SC
常见 PDF 输出失败的三个硬性卡点
不是语法错，而是环境或配置层面的“静默失败”：命令无报错但输出 PDF 为空白页、只有第一页、或字体全丢失。这些问题不会在 Sublime 控制台提示，必须看终端输出。
-
Failed to load font：不是字体文件路径错，而是pdf-fontsdir指向目录里缺少对应字重（如只放了-Regular.ttf，但主题里写了bold_font_name: Noto Sans CJK SC Bold） -
undefined method `visit'或stack level too deep：通常因文档中用了不被asciidoctor-pdf支持的宏（如include::嵌套过深、或含未转义的%符号） - PDF 无页眉页脚/水印：主题文件没被正确加载，检查是否用了
-T data/themes/chinese.yml参数；注意-T是指定主题路径，不是--theme
真正耗时间的从来不是写内容，而是让中文字体、页码格式、代码块边框这些细节在每台机器上都一致跑通。建议把 asciidoctor-pdf 命令封装成 Shell 脚本或 Sublime Build System，并把 fonts/ 和 data/themes/ 作为项目内固定结构一起提交——否则换一台电脑，又得重新调字体路径。
