Using AsciiDoc to write my two books

In the past period of six months when I roamed around Central America, among the six projects that I launched—two where books that I wrote. The first book is about technical writing: Technical Writing for Software Engineer - A Handbook. The second one, which I wrote together with my wife, is about getting into tech: From Applicant to Employee - Your Blueprint for Landing a Job In Tech.

When you decide to write a book, you need to choose what tool to use. Among the most used one are Word (could be Microsoft or Google Docs), and Scrivener—which is the go-to app for writing. But I’m special, so at first I wanted to use Markdown.

Why Markdown, and why not?

Markdown is a fantastic format. It supports all the needed text styles such as italic, bold, and for non-supported styles like underline, you can always use HTML (in that case <ins> tag). And as some of you might know, this very blog you are reading at the moment, is written in Markdown. In short—I really like Markdown. Moreover, I wanted to use the same tools (NeoVim) as I do with my blog, so Markdown was the first obvious choice.

However, as it turned out, Markdown is awful for books, or any technical documentation longer than an average blog post. When writing a book, you need to have support for different elements which Markdown does not support natively, and without hacking. Examples could be: multipage documents, admonitions (those tip or warning boxes you see in many technical books), example blocks, etc.

I didn’t even mention things like: converting the Markdown files to PDF and EPUB, adding cover page, support for referencing other pages/chapters, etc. Of course, most of these issues can be hacked around. My blog has support for admonitions, but I use a custom remark plugin. Referencing other pages can be done using wiki-link styles, but they are not supported by Markdown parsers, and you need to bring in third-party plugins to your Markdown parser of choice.

And bundling a bunch of .md files into a PDF, can be hacked together with tools like pandoc—which is a great piece of software if you need to convert various text formats from one another. And in fact, Markdown + pandoc is what I first tried to do with my book. But quickly I learned that it’s too much hassle, and decided to explore other alternatives.

AsciiDoc

Before settling on AsciiDoc, I read about many different formats. Word and Scrivener were ruled out immediately as I didn’t want to learn new tools (in case of Scrivener), and preferred to stay in my environment of keyboard driver writing experience with NeoVim. I looked at tools like DocBook, which was ruled out because it’s heavily XML infested. And finally, I was set on AsciiDoc.

AsciiDoc is very similar to Markdown, but way more powerful. You have the standard elements of the page like headers (but using = instead of #); text styles (*bold*, __italic__); URLs (https://yieldcode.blog[yield code();]); etc. But in addition to the standard formatting elements, you get more things out of the box like admonitions, example blocks, variables that you can reference, table of contents, etc.

The syntax of AsciiDoc is not that hard, especially if you know Markdown already. But one of the greatest things of AsciiDoc, is the software that comes with it: asciidoctor. Not only it has a great AsciiDoc syntax references, but it also acts as a publishing tool chain for converting AsciiDoc to PDF, HTML, DocBook, etc.

Using asciidoctor

I want to give a quick overview of how to set up asciidoctor, especially for PDF. On macOS, brew install asciidoctor will install the program itself, together with support for PDF. In order to add support for EPUB, you will have to install additional ruby gem using gem install asciidoctor-epub3. Consult the manual for your OS to get started.

Converting an AsciiDoc file to PDF, is a very simple task:

asciidoctor -r asciidoctor-pdf -b pdf -o out.pdf in.adoc

This command will convert in.adoc to out.pdf using pdf backend (-b) via requiring asciidoctor-pdf library (-r). Since AsciiDoc supports including other AsciiDoc files, you can have a one main.adoc that contains all your book information and metadata, and includes all other .adoc files which are chapters or appendixes.

I could end here, but I want to cover some more features. With EPUB you don’t have much room to play. The way EPUB is displayed in terms of fonts and theme—depends a lot on the device where it’s being rendered. PDF, however, is different, and you have more control over it.

When converting AsciiDoc to PDF, you can use a theme that will define how your PDF will be rendered. You control the theme with two CLI arguments:

• pdf-themesdir: accepts a directory where a bunch of yml files named theme-{}.yml will exist
• pdf-theme: accepts a string, which is the name of the theme

So, if inside your themesdir you have a file named theme-book.yml, you can pass pdf-theme=book to the tool in order to use your theme.

There is a default theme that asciidoctor will use if you do not specify one, but if you want to at least change the fonts, you will have to create your own theme. Luckily, you don’t need to create an entire theme from scratch, you can just extend the default theme and overwrite the parts you want/need. In addition to that, there are many themes you can find on the internet that you can use. And in case you do want to create a custom theme, here is the documentation.

Tying it all together with Makefile

The AsciiDoc for my two books lives inside a git repository. From here, I build it to PDF and EPUB using asciidoctor and upload to online stores. I want to create a CI/CD pipeline, at some point, that will build the books and upload them automatically, but for now I don’t have many revisions, so I do it manually.

However, I do automate the generation process with Makefile. For each book, I have a book.mk file that generates both EPUB and PDF files of the book. Then, each book.mk is included in the main Makefile which I run every time I want to generate a book.

Additional tools I use

In addition to AsciiDoc and NeoVim, I use some other tools that helped me with writing my books. Inside NeoVim I use ltex which is language server that runs spell checking using LanguageTools. I used macOS built it text-to-speech in order to do proofreading, in addition to proofreading myself multiple times.

For complicated sentences, I used Hemingway Editor in order to simplify them. The thing with Hemingway though, is to not just follow its recommendation. I believe that sometimes it’s fine to have complex sentences, or sentences in passive voice. But it’s a good tool nevertheless to improve your writing.

One last advice I want to give you. It’s not mine, I saw it from multiple blogs. Writing one sentence per line. With formats like AsciiDoc and Markdown, you can write one sentence per line, and multiple line will be rendered as one paragraph. You separate paragraphs with blank line.

Writing this way makes it easier to edit specific sentence, or scrap entire sentences. In NeoVim I would just dd or cc a line to delete/edit the sentence. One sentence per line is also a good visual indicator for long sentences, that are candidates for simplification. Lastly, gitdiff is easier on the eyes with one sentence per line. This is how it looks:

Imagine you want to tell a story.
You start with describing the setting.
A forest for example.

Inside this forest, Rust and Go are doing a picnic.
And they eat C++.

That’s it. I hope that if you would like to write a book in the future, that this article will be helpful to you.