How to resolve 'section title out of sequence: expected level 1, got level 2' error in Asciidoctor VS Code extension?

Question

I use the Asciidoctor VS Code Extension to edit my AsciiDoc project. My codebase has a structure with several layers of nested folders, and I use include::./folder/file.adoc[] to include lower-level headings. For example, the book includes multiple chapters with several sections.

However, I encounter the following error message in the editor:

section title out of sequence: expected level 1, got level 2 asciidoctor.js

File Structure

root/
├── book.adoc
└── chapters/
    ├── chapter1.adoc
    ├── chapter2.adoc
    ├── ...
    └── sections/
        ├── section1.adoc
        ├── section2.adoc
        └── ...

Main Document (book.adoc)

= Book Title
:toc:
:toclevels: 3

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

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

Chapter 1 (chapters/chapter1.adoc)

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

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

Section 1 (sections/section1.adoc)

Content for section 1.1...

Section 2 (sections/section2.adoc)

Content for section 1.2...

What I've Tried

1. Ensuring the main document starts with a level 1 heading.
2. Verifying that included files have the correct heading levels.

Question

How can I resolve the "section title out of sequence: expected level 1, got level 2" error in the Asciidoctor VS Code extension? Is there a specific way to structure nested AsciiDoc files to avoid this error?

Answer 1

For one thing, in Main Document (book.adoc), "==Chapter Two" is missing a space after the "==", so it's not being interpreted as a level 1 heading. For another, I always put a blank line above every "include:: ..." because you never know when having the first line of the included file butt up against the previous line causes an unexpected result (e.g. two paragraphs being considered one long paragraph).