Includes

Including Files

With the include directive, you can embed content from other files into your document. This is useful for reusable text snippets, shared headers or footers, or to keep large documents organized.

The syntax is simple:

include::path/to/file.adoc[]

The content of the included file is inserted at this point as if it were written directly in the document.

Options for Includes

You can control which part of a file is included:

Option Effect

lines=5..10

Include only lines 5 to 10

tag=example

Include only the marked region "example"

leveloffset=+1

Shift headings one level deeper

opts=optional

No error message if file doesn’t exist

Example with line selection:

include::code/example.py[lines=1..20]

Tagged Regions

For precise control, you can mark regions in the source file:

In the file to be included:

# tag::important[]
def important_function():
    return "This function will be included"
# end::important[]

def other_function():
    return "This one won't"

In the main document:

include::functions.py[tag=important]

This way you include only the marked region – ideal for code examples that you want to keep up to date.

With Composite Documents, chapters are automatically included. The include directive is primarily useful for text snippets and code examples.
More details on include options can be found in the Manual.