This guide will help you understand how all of the pieces fit together on Kitabu.
This guide is designed for beginners who want to get started with Kitabu from scratch. However, to get the most out of it, you need to have some prerequisites installed:
To install Ruby, consider using RVM or rbenv, both available for Mac OSX and Linux distros. If you’re running a Windows, well, I can’t help you. I don’t even know if Kitabu runs over Windows boxes, so if you find any bugs, make sure you let me know.
PrinceXML is the best HTML to PDF converter available. You can use advanced CSS features to style your book in any way you want. But good things don’t come for free, and PrinceXML is no exception. The Professional License, which you grant you a installation on a single computer by a single user costs 495USD. If you don’t like the price tag, consider using DocRaptor when you’re ready to publish your book.
To install PrinceXML, go to the website and download the correct version for your platform; you can choose from Mac OSX, to Linux and Windows.
KindleGen is the command-line tool that allows you to convert e-pubs into .mobi
files. You can’t sell these files, though.You can, but that would be a violation of Amazon’s terms of use. So if that’s the case, consider using Calibre for this task.Calibre is not perfect, but does a good job.
If you’re running Homebrew on the Mac OSX, you can install it with brew install kindlegen
. Go to KindleGen’s website and download the appropriate installer otherwise.
You can create chapters by having multiple files or directories. They’re alphabetically sorted, so make sure you use a prefixed file name like 01_Introduction.md
as the file name.
If you’re going to write a long book, make sure you use the directory organization. This way you can have smaller text files, which will be easier to read and change as you go. A file structure suggestion for a book about Ruby on Rails would be:
getting-started-with-rails
├── text
└── 01_Guide_Assumptions.md
└── 02_Whats_Rails.md
└── 03_Creating_A_New_Project
└── 01_Installing_Rails.md
└── 02_Creating_The_Blog_Application.md
└── 04_Hello_Rails
└── 01_Starting_Up_The_Web_Server.md
└── 02_Say_Hello_Rails.md
└── 03_Setting_The_Application_Home_Page.md
└── ...
Notice that the file name does not need to be readable, but it will make your life easier.
Kitabu uses Route as the syntax highlight formatter. It emits an output compatible with stylesheets designed for pygments, the Python library used by many.
To highlight a code block, use the fenced block syntax. The following example would be formatted as Ruby.
```ruby
class User
attr_accessor :name, :email
def initialize(name, email)
@name = name
@email = email
end
end
```
The output would be something like this:
class User
attr_accessor :name, :email
def initialize(name, email)
@name = name
@email = email
end
end
If you’re using Sublime Text, make sure you install the Markdown Extended plugin; it enables code syntax highlighting on your Markdown files.
You can also provide inline options such as line numbers and inline rendering.
```ruby?line_numbers=1
class User
attr_accessor :name, :email
def initialize(name, email)
@name = name
@email = email
end
end
```
This would be rendered like this:
1 2 3 4 5 6 7 8 |
class User attr_accessor :name, :email def initialize(name, email) @name = name @email = email end end |
Rouge comes with dozens of lexers. Check out this list, generated dynamically when you export your e-book.
apache
applescript
c
clojure
coffeescript
common_lisp
conf
cpp
csharp
css
dart
diff
elixir
erb
erlang
factor
gherkin
go
groovy
haml
handlebars
haskell
html
http
ini
io
java
javascript
json
liquid
literate_coffeescript
literate_haskell
llvm
lua
make
markdown
matlab
moonscript
nginx
nim
objective_c
ocaml
perl
php
plaintext
prolog
properties
puppet
python
qml
r
racket
ruby
rust
sass
scala
scheme
scss
sed
shell
slim
smalltalk
sml
sql
swift
tcl
tex
toml
vb
viml
xml
yaml
And if what you want is not on this list, make you open a ticket on the project.
Sometimes you may find useful to generate content dynamically. Maybe you’re going to read some configuration file, or maybe you just want to define some helpers. Kitabu has support for ERb files; all you need to do is naming your text file as .erb
.
On the previous chapter, we listed all supported Rouge lexers. To do that, I created a helper that looks like this:
module Kitabu
module Helpers
def lexers_list
buffer = '<ul class="lexers">'
Rouge::Lexers.constants.each do |const|
lexer = Rouge::Lexers.const_get(const)
begin
title = lexer.title
tag = lexer.tag
description = lexer.desc
rescue Exception => e
next
end
buffer << '<li>'
buffer << "<strong>#{title}</strong> "
buffer << "<code>#{tag}</code><br>"
buffer << "<span>#{description}</span>"
buffer << '</li>'
end
buffer << '</ul>'
buffer
end
end
end
To use it, I just needed to add <%= lexers_list %>
to my text file. This allows you to create anything you need!
Kitabu comes with some built-in helpers, such as note
. With this helper, you can create a note that generates a HTML structure, so you can easily style it. The syntax for using the note
helper is note(type, &block)
.
<% note do %>
Some text that will be parsed as Markdown.
<% end %>
By default, this will generate a <div class="note info">
tag, but you can use anything you want.
<% note :warning do %>
Some text that will be parsed as Markdown.
<% end %>
Check out the source for a sample on how to create block helpers like note
.
If you want to write a book about Rails, you’re likely to use lots of ERb tags. In this case, make sure you escape the and
markers as <% %>
and <%= %>
; otherwise you’ll have a syntax error.
<%%= Date.today %>
You can generate files as you go. Just execute kitabu export
from your book’s root directory.
$ kitabu export
** e-book has been exported
This command will generate all supported formatsDepend on Prince, html2text and KindleGen being available on your $PATH
. . The generated files will be placed on your output
directory; the following output list only the relevant files.
$ tree output
output
├── images
│ ├── kitabu.png
│ └── kitabu.svg
├── kitabu.epub
├── kitabu.html
├── kitabu.mobi
├── kitabu.pdf
├── kitabu.print.pdf
├── kitabu.txt
└── styles
├── epub.css
├── html.css
├── pdf.css
└── print.css
This can take a while depending on your book size, but usually the process is pretty fast. If you want to generate a specific format faster, provide the --only
flag.
$ kitabu export --only pdf
You can also automatically generate files when something changes. You can use Guard for this, and Kitabu even generates a sample file for you. All you have to do is running bundle exec guard
.
$ bundle exec guard
20:38:10 - INFO - Guard is now watching at '/Users/fnando/Projects/kitabu/examples/kitabu'
** e-book has been exported
After exporting your files (you can use --only pdf
for this), upload files to somewhere public, possibly your Dropbox account. You can even use curl; since the command is quite long, you can view it at https://gist.github.com/fnando/de555a08e7aab14a661a.
This guide will help you understand how all of the pieces fit together on Kitabu.
Copyright (C) 2015 Nando Vieira.