This project contains a template used to write eBooks using AsciiDoc, Git, and any plain text editor in Mac OS X.
The aim of the project is to provide a boilerplate used to generate eBooks in several formats on one operation:
- Self-contained HTML
- ePub
- Kindle
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 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.
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.
Follow these instructions to install the required libraries in Mac OS X:
- Install Homebrew if not already installed.
- If already installed, remember to run
brew update; brew upgrade
.
- If already installed, remember to run
- Download and install
asciidoc
using Homebrew:brew install asciidoc
- Install source-highlight with Homebrew (this will install Boost
as a dependency):
brew install source-highlight
- Install the
dblatex
package with Homebrew:brew install dblatex
- If the above command does not work, follow the instructions here:
https://gist.github.com/dustinschultz/6554087
- Download the kindlegen tool and install it in the following
path:
/Applications/KindleGen_Mac_i386_v2_7/kindlegen
- Make sure AsciiDoc and dblatex are properly installed.
- Execute the
make
command. This will create the PDF, ePub and HTML versions of the book. make pdf
,make html
,make epub
andmake kindle
each generate the specified version of the booklet.make clean
removes the_build
folder.
The .mobi (Amazon Kindle) version requires the kindlegen tool.
After the build process completes, the compiled eBooks will be available
at the _build
subfolder.
See the LICENSE.md file.