Template to create PDF, ePub and Kindle books with Asciidoctor
CSS Makefile Swift
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Template for Writing an eBook

This is a new version of the classic template for eBooks.

Design Guidelines

Why using such a complex setup instead of just using a simpler tool like Word or Pages?

  • The primary motivation of this template is versioning. Being able to use plain text files as input for the book brings the possibility of versioning each change individually using Git, Subversion or any other similar tool. This also opens up the door to collaboration among team members when editing a document.

  • The second motivation is to separate the presentation and the layout of the final book from its contents. Other output file types could be added in the future.

  • This also brings the possibility of using any text editor in just about any operating system; files are just plain text files that can be edited with gEdit, Notepad, Emacs, Vim, TextEdit, or any other similar tool.

  • Markup languages like Markdown or Asciidoc (used in this template) are simpler and more readable than LaTeX or other SGML-like languages, making the files readable and lean even when edited in a text editor without any syntax highlighting or formatting support.

  • Finally, being able to streamline the creation of the three versions of the book in just one command-line operation allows the whole setup to be automatized.

The choice of Asciidoctor comes from the following features:

  • Syntax highlighting of Swift code in all outputs (Pandoc does not support Swift at the moment.)

  • Multi-file projects (Pandoc, because of Markdown, does not support the include mechanism that AsciiDoc provides.)


This toolkit started as a pure LaTeX workflow in 2009. In late 2011 the system moved to Markdown and it used Pandoc to generate the artifacts. In 2012 the choice was AsciiDoc, and in 2016 this new system was finally developed, using AsciiDoctor.

How To Use

The master.asciidoc file at the root of this project provides the guiding structure of the book. Chapters can be shuffled around, independently of their contents or internal structure.

Individual chapters are stored in the chapters folder, one file per chapter.

Images are stored as PNG files in the images folder. Data files (XML, CSV, etc,) are located in the data folder.

The Makefile creates a temporary _build folder, copies all the different elements in it (the master file, the chapters and the images) and commands the execution of the whole toolchain in order to get the final result:

  • Self-contained HTML5

  • PDF

  • EPUB3

  • Kindle (.mobi)

UML diagrams are generated by text through PlantUML.

  1. Execute the make command. This will create the PDF, ePub and HTML versions of the book.

  2. make pdf, make html, make epub and make kindle each generate the specified version of the booklet.

  3. make clean removes the _build folder.

After the build process completes, the compiled eBooks will be available at the _build subfolder.

Requirements and Installation Instructions

macOS (Sierra)

Before using this template, make sure to have Homebrew and Rubygems installed, then run the following commands to install the required dependencies:

$ xcode-select --install # (required for nokogiri, itself a requirement for asciidoc-epub3)
$ brew install plantuml glib gdk-pixbuf cairo pango cmake libxml2
$ gem install pygments.rb kindlegen asciimath asciidoctor asciidoctor-diagram asciidoctor-mathematical
$ gem install asciidoctor-pdf asciidoctor-epub3 --pre

Install the font dependencies for asciidoctor-mathematical:

cd ~/Library/Fonts; \
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf

If you experience compilation problems with asciidoctor-mathematical you can brew link gettext --force if needed. Follow the installation instructions from the project in case of issues.

Ubuntu Linux (16.04)

The libraries used in this template require liblasem which might not be available in your distribution. You should install it manually (well, at least I had to.)

  1. Download http://ie.archive.ubuntu.com/gnome/sources/lasem/0.5/lasem-0.5.0.tar.xz

  2. Extract the file, cd into it and then ./configure & make & make install

  3. sudo cp /usr/local/lib/liblasem-0.6.so /usr/lib/liblasem.so

Install the following libraries:

$ sudo apt-get install plantuml cmake ruby-dev libxml2-dev libcairo2-dev libpango1.0-dev bison flex libgdk-pixbuf2.0-dev libffi-dev ttf-lyx
$ sudo gem install pygments.rb kindlegen asciimath asciidoctor asciidoctor-diagram
$ sudo gem install asciidoctor-pdf asciidoctor-epub3 --pre
$ sudo MATHEMATICAL_SKIP_STRDUP=1 gem install mathematical
$ sudo gem install asciidoctor-mathematical


See the LICENSE.md file.