Verkilo is a Ruby command line script wrapped around Pandoc that compiles Markdown files in a nested directory into a finished product. Use with the Verkilo template repository to create your own book.
Note: Verkilo has not been tested on Windows or Linux, though it is more likely to work on Linux since Mac OSX and Linux are both BSD derivatives. (If you find success or problems using other formats, please create an issue.)
Novel writing should focus on the content, and let the formatting take care of itself. I believe in leveraging open-source to the extent practical. Since large-form fiction writing is straight text, Markdown is ideal. This may not be as well suited for non-fiction that relies heavily on tables or code examples. Provided the images are the right size (300 DPI), they should work fine.
Verkilo (CLI)
- Table of Contents
- Compilation. Consolidates a (nested) Directory of Markdown files (
*.md) into a single document in the following formats:- PDF - Creates a PDF leveraging LaTeX book format (not memoir).
- ePUB - Creates an ePUB which can then be converted into MOBI for Kindle.
- HTML - Creates a single-page HTML document for easy browser reading.
- DOCX - Creates a Microsoft Word Document that most editors prefer.
- Word count. Provides a word count of the complete document. This should be helpful when putting together price estimates for editors, determining book length, or tracking writing progress.
To install Verkilo:
- Create directory
~/.verkilorc - Move
templatesdirectory into~/.verkilorc(~/.verkilorc/templates) - Install Pandoc (see dependencies)
- Copy verkilo to a bin directory of your choosing in your
$PATH. (I use~/bin, but could be/usr/local/bin) and ensure it has execute permissions (chmod +x verkilo)
- All code written in Ruby
- Requires Pandoc.
- Requires certain Google Fonts (see Fonts below).
To use Verkilo:
verkilo pdf great-national-novelcreates a PDF against the great-national-novel directory.verkilo epub great-national-novelcreates an ePUB against the great-national-novel directory.verkilo html great-national-novelcreates an HTML page against the great-national-novel directory.verkilo docx great-national-novelcreates a Word doc against the great-national-novel directory.verkilo book great-national-novelcreates both a PDF and ePUB against the great-national-novel directory.
The formatted documents will be dropped into the build/ directory.
One feature of the LaTeX Memoir package is Plain / Fancy Break. In print, the plain/fancy break appears as vertical white space (three blank lines typically) between two sections, or a symbol denoting the break when it appears at the bottom of a page. While Verkilo does not use Memoir class, we did borrow the Fancy Page Break. Your PDF will benefit from these expected behaviors. Other formats will show a horizontal rule.
To create a plain/fancy break, use the Horizontal Rule markup. Here is an example of both plain & fancy breaks (the border denotes page edges ala the crop: true attribute).
paragraph text here
* * *
paragraph text hereVerkilo uses Pandoc allows for some configuration using YAML. This is accomplished in one of two ways:
- If you are writing multiple books (i.e., a series) that will share attributes, you put those into a
metadata.ymlfile in the root directory to those books. - For attributes related to a specific book in that series, you can put those as YAML Front Matter in any of the Markdown files, or as a dedicated Markdown file.
Pandoc uses the metadata.yml as a default configuration that YAML Front Matter in the *.md files overrides. So, if there are broad configurations that should apply everywhere with a few exceptions, then a mix of the metadata.yml and YAML Front Matter should suffice. See Pandoc's Documentation on LaTeX variables for more information.
Warning: the last YAML Front Matter metadata setting wins, so if you are using them in multiple files, you will experience odd side effects.
Note. Settings relating to geometry, margins, and line stretch are governed by trim size in Verkilo.
Examples of both the metadata.yml and front matter metadata are available in the Verkilo template repository. YAML Front Matter in this context is a block of YAML code at the top of the document. Jekyll's documentation on YAML Front Matter describes it better than I could.
Verkilo configures three default fonts, but you may reconfigure them provided they are available when using the LaTeX font packages listed here. See Pandoc fonts for LaTeX for more information.
Fonts are configured in either the metadata.yml or the in-document Frontmatter.
The LaTeX packages used for font assignments are:
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{xltxtra}
| Family | Default | Attribute |
|---|---|---|
| Serif | Libre Baskerville | seriffont: Libre Baskerville |
| Sans-Serif | Libre Franklin | sansfont: Libre Franklin |
| Monospace | Inconsolata | monofont: Inconsolata |
Why default Baskerville, Franklin & Inconsolata? Both Libre Baskerville and Libre Franklin have been optimized for use on screen. Baskerville is nice and readable, so ideal for use as body text, while Franklin is better suited to headlines. Inconsolata pairs with Baskerville & Franklin as they all share similar traits (double-story g & a, etc.). See the Libre Baskerville / Franklin / Inconsolata pairing image.
Here is an example of customizing fonts based on the Source Pro series:
seriffont: "Source Serif Pro"
sansfont: "Source Sans Pro"
monofont: "Source Code Pro"
The PDF option includes multiple trim sizes, depending on your target form factor. The Word document has a fixed trim size (Letter). The ePUB and HTML lack trim sizes. Metric measures rounded to 2 digits in the table. All measures are in metric in the LaTeX macros. (US Customary Measures are defined by their Metric equivalent.) When calculating trim size, we compared commonly used sizes and those offered by KDP.
| Trimsize | Paper Size |
|---|---|
| Letter | 8-1/2" x 11" |
| LargeTrade | 8" x 10" |
| Textbook | 7" x 10" |
| Trade | 6" x 9" |
| Digest | 5-1/2" x 8-1/2" |
| SmallTrade | 5-1/4" x 8" |
| Novella | 5" x 8" |
| AFourSize | 21cm x 30cm |
| UKAFormat | 11cm x 18cm |
| UKBFormat | 13cm x 20cm |
- Top and Inner margins are 2cm (~3/4").
- Outer and bottom margins are 17mm (~5/8").
- When attribute
bleed: trueis set, then the paper size and margins are increased by 3mm wide and 6mm high. (I don't think we can bleed an image, though.) - Set attribute
crop: trueto see what a given size looks like scaled properly on a letter-sized printout.
Warning: Failure to use one of the listed trim sizes will cause the compilation to fail. Defaults to trimsize: Trade.
Line hight is determined by trim size so that a 10pt font size will yield 35-40 lines per page when compiling to PDF.
Verkilo attempts to use the repository's git tag in the output filename. When that tag is missing, the git command throws the fatal: No names found, cannot describe anything error. This does not affect the final output.
The fontspec error: "font-not-found" error means you do not have the font listed with the error installed. If you are using the out-of-the-box fonts, you can install them from Google:
This script is licensed under an MIT license.