How to write your book with AsciiDoc

This article is based on the AsciiDoc Book Starter template repository on GitHub for authoring books using AsciiDoc.

huge shout out to Dan Allen who’s the co-lead of Asciidoctor project and open-source asciidoctor-pdf extension for generating PDFs from AsciiDoc. Dan’s work has been instrumental to the success of self-published authors such as myself, and I’m incredibly grateful for his work ❤️ Thank you Dan!

I’ve briefly explored other formats such as Markdown, Latex, and Pandoc but I’ve found AsciiDoc to be the most flexible and powerful format for authoring books. It is easily readable and writable to a human, has a lax syntax and good set of defaults for authoring books, and it can be easily converted to other formats such as PDF, ePUB and HTML.

AsciiDoc is also a very powerful format for authoring technical documentation, and is widely used in the media and content publishing industry, such as in O’Reilly’s books.

Basics of AsciiDoc and Writing

An important observation to get started when authoring a book with AsciiDoc is the notion of the language vs the implementations. AsciiDoc is a language that’s intended to be a lightweight semantic markup. To generate output from AsciiDoc we use text processor tools such as Asciidoctor, which is free and open source.

Get up to date with the latest AsciiDoc syntax and features by reading the AsciiDoc User Guide.

Features of my AsciiDoc Book Starter

My AsciiDoc Book Starter GitHub repository features the following advantages to help you get started quickly with your book authoring journey.

AsciiDoc book authoring

Book authoring experience provides the following features with this repository:

• Table of Contents (TOC) generation.
• Template prelude chapters: A Preface, and a Forward.
• Template chapters with commonly used formatting in books.
• Chapters are structured into their own chapter directories so they can be co-located with their images and other assets, such as code snippets.
• A PDF output that uses a theme, and can be customized.
• A PDF output that uses custom fonts (Google’s open fonts family). Specifically, an Open Sans font for the body text, and a Source Code Pro font for source code snippets and inline code.

AsciiDoc book generation

Batteries-included book generation features:

• No need for a local installation of Asciidoctor, as the book generation is done via Docker.
• No need for special CI setup, as the book generation is done via Docker.
• Docker-based scripts to generate the book in various formats, including PDF, HTML and ePUB.

Getting Started with AsciiDoc Book Starter

We start off by getting familiar with the repository structure and the various files that are part of it.

The top-level directory structure looks like this:

.
├── README.md
├── book
│   ├── chapter-01.adoc
│   ├── preface.adoc
│   ├── foreword.adoc
│   ├── index.adoc
│   ├── fonts/
│   ├── images/
│   └── themes/
├── create-book-epub.sh
├── create-book-pdf.sh
└── interactive-asciidoctor-shell.sh

The book directory is where the book content is stored:

• The index.adoc file is the main entry point for the book, and it’s where we include all the other chapters and prelude chapters.
• The images/ directory is where you can store images that are used in the book.
• The chapter-01.adoc is an example chapter that you can use as a template for your own chapters.
• In the same directory, you’ll find the theme-able PDF themes directory, and the fonts directory which contains the fonts used in the book.

Generate the AsciiDoc book

The following sections describe how to generate the book in various formats and without requiring you to have a local Ruby runtime environment or otherwise, since it is all done via Docker.

Building the AsciiDoc book locally

To build the book locally, you’ll need to have Docker installed on your machine. Once you have Docker installed, you can run the following command to build the book in PDF format:

./create-book-pdf.sh

Then you can find the generated PDF file in the book directory. If you’re on a macOS, you can open it with your default PDF reader as follows:

open book/index.pdf

Helpful AsciiDoc Scripts

The asciidoc book starter repository also provides a few helpful scripts to help you generate other book output formats and debug the asciidoctor tool:

• create-book-epub.sh - Generates the book in ePUB format.
• interactive-asciidoctor-shell.sh - Starts an interactive shell inside the Docker image with the asciidoctor tool installed.

AsciiDoc Book Assets

Static assets for the book are stored in the book directory, and include the following:

• The images directory is where you can store images that are used in the book. Inside this directory is a cover.jpeg image used for the book’s cover, and a space.jpeg used as an example for an image in the book.
• The fonts directory is where you can store fonts that are used in the book. It currently houses the Open Sans and Source Code Pro fonts, both with their original .zip file archived as downloaded from the Google Fonts website as well as extracted each to its own directory.

Summary

In conclusion, I found AsciiDoc to be a bit overwhelming and a steep learning curve to begin with, but once you conquer that hill, I’m sure you’ll find AsciiDoc a great format for authoring books.

I hope you’ll find the AsciiDoc Book Starter repository useful for your own book authoring journey.

Another shout out to Alex DeBrie 🤗 who’s the author of The DynamoDB Book and who helped me get started with my own self-published AsciiDoc book using his repository as a starting point for the AsciiDoc setup.