When we use the
include directive to include another document we can must make sure the included document fits the levels of our main document. For example the included document shouldn't have level 0 headings if the main document already contains a level 0 heading. We can change the level offset in the main document before including another document. This will change the heading levels for the included document so all heading rules are okay.
To change the level offset we use the document attribute
leveloffset. It is best to use a relative value, so if the included document also contains included document the output will still be okay and the heading rules still apply. Alternatively we can use the
leveloffset attribute for the
include directive. In the following sample document we include other files with a level 0 heading:
// File: book.adoc = Include other files // Include section numbers. :sectnums: // The file `chapter1.adoc` has a level 0 heading. // To make sure it can be included we // increase the level offset. :leveloffset: +1 include::chapter1.adoc // Reset level offset. :leveloffset: -1 // Or use :leveloffset: 0 // We can also use the `leveloffset` attribute // of the `include` directive. The level offset // is then automatically reset. include::chapter2.adoc[leveloffset=+2]
Here is the source for the included files:
// File: chapter1.adoc = First chapter Sample document to be included.
// File: chapter2.adoc = Second chapter Sample document to be included.
When we transform
book.adoc to HTML with Asciidoctor we get the following result:
Written with Asciidoctor 1.5.4.