如何解决Asciidoctor VS Code扩展中的标题序列错误？

问题分析 #

你遇到的“section title out of sequence: expected level 1, got level 2”错误，核心原因是主文档与被引入文件的标题层级冲突——Asciidoctor要求标题层级必须按顺序递进，不能在二级标题下直接插入同级的二级标题。

解决方案及规范嵌套结构 #

1. 调整被引入文件的标题层级 #

根据你当前的主文档结构（已定义二级章节标题），被引入的章节文件不能再使用二级标题（==），必须从三级标题（===）开始，作为主文档对应章节的内容补充。

示例结构：

• book.adoc（主文档）：

= Book Title
:toc:
:toclevels: 3

== Chapter One
include::./chapters/chapter1.adoc[]

== Chapter Two
include::./chapters/chapter2.adoc[]

• chapters/chapter1.adoc（章节文件）：

=== Section 1.1
这里是第一章第一小节的内容。

=== Section 1.2
include::./sections/section1.adoc[]

• chapters/sections/section1.adoc（小节文件）：

==== Subsection 1.2.1
这里是第一章第二小节的子内容。

2. 另一种规范模式：独立章节文件引入 #

如果希望章节文件本身是完整的（自带二级标题），则主文档不需要手动定义二级标题，直接引入完整章节文件即可：

示例结构：

• book.adoc（主文档）：

= Book Title
:toc:
:toclevels: 3

include::./chapters/chapter1.adoc[]
include::./chapters/chapter2.adoc[]

• chapters/chapter1.adoc（完整章节）：

== Chapter One
=== Section 1.1
章节内容...

include::./sections/section1.adoc[]

• chapters/sections/section1.adoc（小节文件）：

=== Section 1.2
==== Subsection 1.2.1
小节子内容...

3. 额外排查要点 #

• 检查include路径：确保路径正确，避免引入错误的文件（比如误引入主文档或层级不匹配的文件）
• 规范标题格式：标题符号与文字间必须有空格（比如主文档中的==Chapter Two需改为== Chapter Two）
• 重置编辑器缓存：重启VS Code或重新加载Asciidoctor插件，清除可能的缓存错误提示

内容的提问来源于stack exchange，提问作者Foad S. Farimani