Writing technical books in AsciiDoc

Sun, 30 Nov 2025 00:00:00 +0000

Writing technical books in AsciiDoc is an excellent choice thanks to its simplicity, power, and integration with modern documentation and publishing tools. Here are the best practices and tools to streamline your writing and publishing process.

Project Structure and Organization

Recommended tree

Organize your project clearly and modularly. Example:

my-book/
├── manuscript/
│ ├── preface.adoc
│ ├── chapter1.adoc
│ ├── chapter2.adoc
│ └── ...
├── images/
│ ├── diagram1.png
│ └── ...
├── includes/
│ ├── glossary.adoc
│ └── appendices.adoc
├── styles/
│ └── theme.yml
├── build.sh
└── book.adoc

Modular files: One file per chapter or major section to ease maintenance.
Includes: Use the include::file.adoc[] directive to assemble the book from multiple files.
External resources: Place images, source code, and appendices in dedicated folders.

AsciiDoc Best Practices

Syntax and style

Hierarchical headings: Use =, ==, ===, etc. to structure content.

Code blocks: Use backticks with the language for syntax highlighting:

[source,python]
-----
def hello():
 print("Hello, AsciiDoc!")
-----

Notes and warnings:

NOTE: Important information.

WARNING: Pay attention to this step!

Lists and tables: Prefer CSV-style tables for complex data.

Variables: Define variables for versions, software names, etc.:

:version: 1.0
:software: Python

This book covers {software} version {version}.

Pachadata Blog on Rudi Bruchez

Writing technical books in AsciiDoc

Project Structure and Organization

Recommended tree

AsciiDoc Best Practices

Syntax and style