Offset Section Levels
When your document gets large, you can split it up into subdocuments for easier editing.
= My book include::chapter01.adoc include::chapter02.adoc include::chapter03.adoc
|Note the blank lines before and after the include directives. This practice is recommended whenever including AsciiDoc content to avoid unexpected results (e.g., a section title getting interpreted as a line at the end of a previous paragraph).|
leveloffset attribute can help here by pushing all headings in the included document down by the specified number of levels.
This allows you to publish each chapter as a standalone document (complete with a document title), but still be able to include the chapters into a primary document (which has its own document title).
You can easily assemble your book so that the chapter document titles become level 1 headings using:
= My Book include::chapter01.adoc[leveloffset=+1] include::chapter02.adoc[leveloffset=+1] include::chapter03.adoc[leveloffset=+1]
Because the leveloffset is relative (it begins with + or -), this works even if the included document has its own includes and leveloffsets.
If you have lots of chapters to include and want them all to have the same offset, you can save some typing by setting
leveloffset around the includes:
= My book :leveloffset: +1 include::chapter01.adoc include::chapter02.adoc include::chapter03.adoc :leveloffset: -1
The final line returns the level offset to 0.
Alternatively, you could use absolute levels:
:leveloffset: 1 //includes :leveloffset: 0
Relative levels are preferred. Absolute levels become awkward when you have nested includes since they aren’t context aware.