Lot's of people ask me about the stack I used to build my books. And a while ago I open sourced one of them on GitHub.
Toolchains
You see, I actually have two different stacks I use to build my books. Deployment from Scratch was build with Markdown, LaTex, and Pandoc. My other books Kamal Handbook and Test Driving Rails were built using AsciiDoc and Asciidoctor, a Ruby open source publishing toolchain. And that's the one I actually open sourced a while ago.
AsciiDoc
AsciiDoc is a lightweight markup language that is designed to be easy to read and write, while also allowing for the creation of structured documents. It is commonly used for writing technical documentation, user manuals, and other types of content that require a clear and structured format. AsciiDoc uses simple and intuitive syntax to define headings, lists, tables, code blocks, and other elements in a document.
And that brings me to AsciiDoctor which is a tool that is used to convert AsciiDoc documents into various output formats, such as HTML, PDF, and EPUB. AsciiDoctor enhances the functionality of AsciiDoc by providing additional features like syntax highlighting, cross-references, and customizable themes. It simplifies the process of generating high-quality documentation or, well, creating small technical books.
If you have a Ruby background you might also want to check out my older post called Ruby for ebook publishing which mentions some other tools as well.
The template
My AsciiDoctor book template is super simple. In fact, so simple it will make you question if you need a template at all. The tool is that easy. The template focuses on basic features that are enough to produce a small technical book. Here's what you'll get:
- Cover image
- Code blocks with syntax highlighting
- Images
- Notes
- Tables
This is all I needed to build my two books for PDF and ePUB. I wanted to use some other features like footnotes but they were not showing up well in ePUB readers, so I just kept it simple.
How to use it
Since Asciidoctor is written in Ruby you need to install Ruby first if you don't have it. Then you just check out the repo and install the dependencies:
$ git checkout [email protected]:strzibny/asciidoc-book-template.git
$ cd asciidoc-book-template && bundle install
Once that's finished, you can write your book in book.ascii
and build it with a single command:
$ foreman run print
You can also specify pdf
or epub
instead of print to get just a single artifact.
