Writing technical books in AsciiDoc

Writing technical books in AsciiDoc is an excellent choice thanks to its simplicity, power, and integration with modern documentation and publishing tools.

  2 minute read  

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

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}.

Managing references

  • Internal links: Use <<heading-id>> for anchors.
  • Bibliography: Use separate .adoc files and the bibliography::[] directive.

Essential Tools

Editors and plugins

Book generation

  • Asciidoctor: Reference tool to convert AsciiDoc to HTML, PDF, EPUB.

    • Install: gem install asciidoctor
    • HTML generation: asciidoctor book.adoc
    • PDF generation: asciidoctor-pdf book.adoc (requires asciidoctor-pdf).

  • Docker: To avoid dependency issues, use a Docker image with Asciidoctor preinstalled:

    docker run -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor book.adoc

Automation

  • Makefile or Bash script: Automate build and validation.

    # build.sh
asciidoctor book.adoc
asciidoctor-pdf book.adoc

  • GitHub Actions: Integrate generation into your CI/CD workflow to validate output on each commit.

Tips

  • Diagrams: Embed diagrams with PlantUML or Mermaid directly in your AsciiDoc.
  • Automated tests: Use asciidoctor-lint to validate syntax.
  • Custom themes: Create a theme.yml file to standardize style (colors, fonts, etc.).

Example book.adoc

= Book Title
:author: Rudi Bruchez
:doctype: book
:source-highlighter: rouge

include::manuscript/preface.adoc[]

== First Chapter
include::manuscript/chapter1.adoc[]

== Second Chapter
include::manuscript/chapter2.adoc[]

Further reading