Mastering the include Directive in AsciiDoc
Learn how to use the AsciiDoc include directive for efficient documentation workflows: Here’s how to modularize your documents.
The include directive is one of the most versatile tools in AsciiDoc, allowing technical writers to manage large documents efficiently by reusing content from external files. This feature is particularly valuable when working on modular projects, where consistency and maintainability are key.
Let’s explore how to master the include directive and make the most of it in your workflow.
What Is the include Directive?
The include directive lets you pull content from other files directly into your AsciiDoc document. Instead of duplicating text or manually copying it, you reference the external file—making updates and modular management seamless.
Basic Syntax
include::path/to/file.adoc[]
This simple command imports the entire content of the referenced file into your document at the specified location.
Best Practices for the include Directive
1. Splitting Large Documents
If your documentation spans multiple chapters or sections, split them into smaller .adoc files and bring them together using include:
= User Manual
include::introduction.adoc[]
include::installation.adoc[]
include::features.adoc[]This keeps files manageable and allows different team members to edit sections without interfering with each other’s work.
2. Including Specific Lines
You don’t always need the entire content of a file. The lines attribute allows you to include only certain lines:
include::file.adoc[lines=10..20]
This imports lines 10 through 20 of the file — perfect for code snippets or targeted content inclusion.
3. Tag-Based Inclusion
For more advanced control, use tags within your file and include only the tagged content.
Tagging the Source File:
Place tag::example[] before and end::example[] after the text you want to tag.
Including the Tagged Block:
include::file.adoc[tag=example]
This now includes all lines inbetween the tags.
4. Dynamic Path Management with Attributes
Use attributes to define paths dynamically, making your documents adaptable across projects.
:docs-path: ../shared-docs/
include::{docs-path}common-setup.adoc[]This way, if the file path changes, you only need to update the :docs-path: attribute rather than modifying every include line.
5. Offset Section Levels
When splitting large documents into smaller subdocuments, managing heading levels becomes essential. Use the leveloffset attribute to adjust headings dynamically when including files.
= My Book
include::chapter01.adoc[leveloffset=+1]
include::chapter02.adoc[leveloffset=+1]
include::chapter03.adoc[leveloffset=+1]This method ensures headings in the included files align correctly with the main document’s structure.
Setting Global Offsets:
Avoid repetitive leveloffset attributes by setting it around includes:
= My Book
:leveloffset: +
1include::chapter01.adoc[]
include::chapter02.adoc[]
include::chapter03.adoc[]
:leveloffset: -1The final :leveloffset: -1 resets the heading level. This approach is especially useful for long documents with many chapters.
6. Include List Item Content
To include external content within list items, combine the include directive with list continuation (+).
Example with Simple Content:
* {empty}
include::item-text.adoc[]
For Complex Content: Use an open block:
* {empty}
+
--
include::complex-item.adoc[]
--This ensures list structures remain intact, even with multi-line or complex includes.
Do's and Don'ts for Using the include Directive
Avoid Circular Includes: Never include a file that references the current file to prevent infinite loops.
Use Relative Paths: Ensure your file paths are relative for portability across different environments.
Combine Includes with Comments: Use comments to indicate where included content comes from for better readability.
Wrapping It Up
The include directive is the backbone of modular documentation in AsciiDoc, offering flexibility and simplicity for managing large documents. Whether you’re splitting content into smaller sections, reusing tagged blocks, or dynamically adjusting paths and headings, include ensures your documentation stays clean, organized, and easy to maintain.
While this guide focuses on mastering the include directive, conditional directives such as ifdef, ifndef, and ifevalprovide additional tools for dynamic content management. To learn more about these directives, refer to the adoc Studio learning path, where they’re covered in detail.
With the right use of include, your documentation workflow will scale effortlessly, saving time and ensuring consistency across projects.
