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 empty 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). |
Manipulate heading levels with leveloffset
The 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: -1The final line returns the level offset to 0.
Alternatively, you could use absolute levels:
:leveloffset: 1
//includes
:leveloffset: 0Relative levels are preferred. Absolute levels become awkward when you have nested includes since they aren’t context aware.