https://github.com/akosma/ebook-template

Template to create PDF, ePub and Kindle books with Asciidoctor
https://github.com/akosma/ebook-template

asciidoc asciidoctor book documentation writing

Last synced: 7 months ago
JSON representation

Template to create PDF, ePub and Kindle books with Asciidoctor

• Host: GitHub
• URL: https://github.com/akosma/ebook-template
• Owner: akosma
• License: other
• Created: 2012-01-20T21:50:55.000Z (over 13 years ago)
• Default Branch: master
• Last Pushed: 2021-09-27T08:46:01.000Z (about 4 years ago)
• Last Synced: 2025-03-03T23:49:50.977Z (8 months ago)
• Topics: asciidoc, asciidoctor, book, documentation, writing
• Language: CSS
• Homepage: http://akosma.github.io/eBook-Template/
• Size: 3.16 MB
• Stars: 190
• Watchers: 13
• Forks: 47
• Open Issues: 1
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE.adoc

Awesome Lists containing this project

README

          
= Template for Writing an eBook

This is a new version of the classic template for eBooks. You can use this

code to kickstart your writing project from scratch.

== 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 http://asciidoctor.org[Asciidoctor] comes from the following

features:

- Syntax highlighting of https://swift.org[Swift] and

  https://kotlinlang.org[Kotlin] code in all outputs

  (http://pandoc.org[Pandoc] does not support Swift at the moment.)

- Multi-file projects (Pandoc, because of Markdown, does not support the

  `include` mechanism that AsciiDoc provides.)

== History

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 http://asciidoc.org[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:

- Unix `man` page

- Self-contained HTML5

- PDF

- EPUB3

- Kindle (.mobi)

UML diagrams are generated by text through http://plantuml.com[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

This section explains the different required libraries, for both macOS and

Ubuntu Linux.

=== 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 epubcheck

    $ 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 https://github.com/asciidoctor/asciidoctor-mathematical[project] in case of

issues.

=== Ubuntu Linux (16.04/16.10/18.04)

Install the following libraries:

    sudo apt-get install -y plantuml cmake ruby-dev libxml2-dev libcairo2-dev \

        libpango1.0-dev bison flex libgdk-pixbuf2.0-dev libffi-dev ttf-lyx \

        intltool

    sudo gem install pygments.rb kindlegen asciimath asciidoctor \

        asciidoctor-diagram epubcheck

    sudo gem install asciidoctor-pdf asciidoctor-epub3 --pre

    sudo MATHEMATICAL_SKIP_STRDUP=1 gem install mathematical

    sudo gem install asciidoctor-mathematical

[Unfortunately](https://github.com/asciidoctor/asciidoctor-epub3/issues/179)

the current versions of Asciidoctor on Ubuntu exhibit a weird behaviour when

using asciidoctor-diagram during the generation of EPUB output.

=== Docker

The project includes a `Dockerfile` which can be built using the following

command:

`docker build -t "ebook-template" .`

Once built, the Docker container can be used as follows on the local folder

where the Makefile is located:

`docker run -v ${PWD}:/workdir ebook-template`

== License

See the LICENSE.adoc file.