Rek Bell

⬟

This is a list of notes I've compiled when came time to learn how to generate PDFs, and e-books with free, open-source software.

A note on TeX

When I first started making books, I used Markdown and Pandoc, as well as a little bit of TeX(bits I grabbed from a collection of posts on StackOverflow) to generate a working document. Pandoc funnels the markdown document into a PDF engine which typesets the whole thing-easy peasy but this way of generating a book has its limits. If you want to center text, to add a custom title page, or a copyright pages, learning a bit of TeX will permit you to modify a text more granularly.

Using Markdown and Pandoc is like flirting with TeX, I saw what this typesetting system can do, and it left me yearning for more. Emboldened by the 5 lines I had learned making Busy Doing Nothing(Ho hooo, yesss, I can do anythiiing), I learned 5 more lines to make Wiktopher, and then another 15, wading into the friendly familiar waters of Pandoc and Markdown all the while. This page is for people who want to just dip their toes into bookmaking, and learning a bit of TeX on the way.

"TeX was designed with two main goals in mind: to allow anybody to produce high-quality books with minimal effort, and to provide a system that would give exactly the same results on all computers, at any point in time."

My way of generating this book is certainly not the best way, but in the end I walked away with two books, and that was my goal :). I learn more TeX with every publication, and hope to work my way to a full publication coded in that language.

See the sources for Wiktopher, and for Busy Doing Nothing.

Contents

If you have plans to export a PDF, you'll need the following:

To generate MOBIs and EPUBs, you'll also need the following:

Now that you've installed all necessary tools, let's begin:

What is Pandoc?

Pandoc is a terminal utility that converts files from one markup format into another. You can convert an HTML page to Markdown, Markdown to PDF, Markdown to EPUB etc. It's a useful tool to create articles, scientific papers, and books.

When generating PDFs, Pandoc's use of LaTeX (a document preparation system) encourages authors not to worry too much about the appearance of their documents but to concentrate on getting the right content. To find out how to install LaTeX, read my tutorial.

Pandoc Markdown

Make sure that the file you want turned into a PDF has an .md extension, and take note of the path to your project file, as you'll need that to generate your PDF later. The next step is to add Pandoc Markdown syntax to the text.

Pandoc Markdown is an extended and slightly revised version of John Gruber’s Markdown syntax. Markdown is a simple, and easy-to-use markup language to format plain-text content. This language is used to annotate a document in a way that is syntactically distinguishable from the text.

For example, to make text bold, add two asterisks on each side of the word:

In January 2016, we bought our first sailboat, a **Yamaha 33**.

Hash symbols preceding a word or phrase make a heading. Be sure to add a space between the hash and the first word:

## Introduction

One hash would make the title bigger, three would make the heading smaller, four even smaller, five even smaller etc. Headings are important too for creating epubs, as Pandoc will use the headers to generate the table of contents of your e-book.

There is no easy equivalent to adding indents in the text, but it is possible by adding a bunch of spaces using:

 

It is very hacky though. I've not yet found a solution for this, not a simple one anyway. When writing paragraphs, always add two spaces after each one if you want spacing between them.

Footnotes. To add footnotes to the text, add a number between square brackets after a specific word, like so: [^1]. An example text:

Licky root[^1] is a popular herb because...

The [^1] will render as a small '1' in the exported version of the text. Then in the document (end, beginning, doesn't matter), add the same number between square brackets again, followed with the footnotes you wish to have (directly following the number). For example:

[^1]: Licky root is a plant that is often brewed as tea.

That text won't appear in the document end, it'll appear on the same page where with the marker. This is what it will look like in the text:

From Markdown to PDF

To generate a PDF from your .md or .txt file, locate your project file using the terminal. Navigate to your project folder. The example below is if you'd saved your project file to Documents, under a folder named myproject.:

cd Documents/myproject/

Enter the following command, replacing filename with the name of your project file, and filename_export with for the final exported PDF file. To format the PDF, I use Tectonic a self-contained TeX/LaTeX engine, powered by XeTeX and TeXLive. I used to install TeXLive packages separately, but it is a bit messy, one system update corrupted my install and so I switched to Tectonic.

Enter the following:

pandoc filename.txt --pdf-engine=tectonic -o filename_export.pdf

In that same folder where you had your .txt file saved, you'll find your Pandoc-generated PDF.

Using Pandoc Markdown Extensions

In Pandoc, you can use extensions (see below) to specify the output of your PDF more granularly, say, if you want to change the paper size, add tables, footnotes etc.

Changing papersize

By default, the Pandoc PDF format is a4. If you want to change it, you'll have to add the following when generating the PDF in the command line:

--variable=geometry:a5paper

Appended with the rest, to generate the PDF from a Markdown file, it'll look like this:

pandoc --variable=geometry:a5paper filename.txt --pdf-engine=tectonic -o filename_export.pdf

If you're file is a .md, change the extension of your project file.

Adding extensions

If you want add tables, you'll have to add an extension. Extensions are specified in the command line when generating a pdf. In the example below, after -- from markdown, I've added a + followed by the extension simple tables. If the extension name has two words, adding an underscore between them is necessary.

--from markdown+simple_tables

You can add more extensions, adding a + inbetween each one. In the example below, I've added both simple tables and citations.

--from markdown+simple_tables+citations

Below is an example of a terminal command for a PDF generated from a .txt file, in a5 format, with the simple tables extension.

pandoc --variable=geometry:a5paper filename.txt --pdf-engine=tectonic --from markdown+simple_tables -o filename_export.pdf

Book cover PDF

If the goal is to make a book for print, say with lulu.com, you won't have to include a cover in the PDF. Lulu demands a separate template. The following is if you want to produce a PDF to be read digitally.

Adding a book cover for a PDF with Pandoc is not straightforward, unless the book is coded in TeX. One technique I used once is to use ImageMagick to convert the cover image into a PDF, and then to combine the PDFs together into yet another PDF.

Save the cover image in your project folder. If you put it in a separate folder, be sure to specify it. Now, use this ImageMagick command to convert the image to a PDF:

convert cover.jpg cover.pdf

To combine the cover with the main text pdf, use Ghostscript:

gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -s OutputFile=filename_final.pdf cover.pdf filename_export.pdf

Paragraph indents and centering chapter headings

Indenting text is possible in a Markdown document by adding a series blank spaces(&nbsp) before the line you wish to indent, but it is better to format it using TeX.

It is difficult for me to explain how to do this because I do not master the use of TeX. But I have found settings that do exactly what I need.

To beautify my chapters and sections, I created a file named titlesec.tex, with the following elements in the document(of course, all numbers are set as zeros, set your own):

\usepackage[bf,tiny,center]{titlesec}
\usepackage{parskip}
\usepackage{indentfirst}
\setlength{\parindent{0pt}
\titlespacing*{\chapter}
   {0pt}% left
   {0cm}% before
   {0em}% after
\raggedbottom

Example of a Pandoc command to generate a PDF that includes the formatting in titlesec.tex:

pandoc --variable=geometry:a5paper filename.md --pdf-engine=tectonic --from markdown+line_blocks+inline_notes --toc -V toc-title:"Table of Contents" --toc-depth=2 --include-in-header=titlesec.tex -o final.pdf

Making a title page with TeX

See the title page for wiktopher. I used similar code to generate a copyright page.

Below is what I used to generate the above page. Making a title page with TeX is completely optional. I didn't make a fancy title page for busy doing nothing, but I really wanted one for wiktopher so I decided to learn some TeX.

This code is saved as a .tex file that I've named titlepage.tex, and is generated as a PDF with Pandoc. All text is centered(\centering) which includes an image on top (\include graphics), the book title(\huge\bfseries), the book subtitle(\LARGE \textsc), the author name (\Large\itshape), the editor name, and the studio name(\large \textsc):

\begin{document}
\begin{titlepage}
   \centering
   \includegraphics{media/image.jpg}\par
   {\huge\bfseries Wiktopher\par}
   {\LARGE \textsc{--- Desert Tales ---}\par}
   \vspace{0.50cm}
   {\Large\itshape Rek Bell\par}
   \vspace{1cm}
   Edited by\par
   Devine Lu Linvega\vspace{1cm}
   \vfill
   {\large \textsc{Hundred Rabbits}\par{ 
   \vfill
% Bottom of the page
   {\large \today\par}
\end{titlepage}
\end{document}

Font sizes range from very small to very big, it affects all text between the curly brackets. Here are all the possibilities:
\tiny, \scriptsize, \footnotesize, \small, \normal size, \large, \Large, \LARGE, \huge and \Huge.

For more information about font style, read this page.

Make the file into a PDF:

pandoc --variable=geometry:a5paper filename.md --pdf-engine=tectonic --include-in-header=titlepage.tex -o titlepage.pdf

As I said, I'm not expert... I don't know how to generate the title page without calling the working source file(the markdown file) in the command, but it's the only way I've gotten it to work. This command will only generate a single page, which in a later step will be combined to the rest of the PDF file using Ghostscript.

Combining all pages into a single PDF

Combining all of the invidually-generated PDFs with Ghostscript:

gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -s OutputFile=filename_final.pdf cover.pdf titlepage.pdf filename_export.pdf

The reason that I generated all of those pages invidiually is because they are generated from two separate .tex files. This is a sort of workaround, to be able to continue using Markdown for the main body text while avoiding heavy use of TeX. A text written entirely in TeX would mean even more customization, but it requires learning a lot more code. I want to get there someday, but I also want to publish books :)... so I am going the slow route.

Making epubs

EPUB is a popular ebook format, but if you convert a Markdown file to an epub it may break some of your formatting. For example, EPUBs ignore the \newpage Markdown tag, but assigning a page break to a specific level of header with css fixes that problem. For EPUBs it is a good idea to use css to control the final look of the document.

First step is to create a blank text file, and to save it as epub.css.

I prefer not to modify the look too much, so I keep my css to minimum. For example:

body {font-size: 14px}
table {font-size: 14px}
h4 {page-break-before: always;}
h2 {page-break-before: always;}
blockquote {font-style: italic;}
img {max-width: 100%}

I don't recommend setting a fixed font size like in the example above, as the font may be too small to read on a phone. I specified a max-width for images otherwise they have a tendency to spill out of the page. Of course, these are only a few of the many things one can do to improve the look of documents with css.

When exporting the file as an EPUB with Pandoc, add the extension like the above example, along with arguments to generate a table of contents from your list of headers, the book's metadata, a book cover and your css file.

Table of Contents: To change the name of the table of the contents generated by Pandoc, add the following command, changing 'custom text' for the desired name of your table of contents:

-V toc-title:"Custom text"

If the table of contents depth is not specified, it defaults to 3 (level 1, 2 and 3 headers will be included in the generated table of contents). To keep the table to a depth of level 2, add:

--toc-depth=2

Metadata file: A metadata file includes all the author, rights and publishing information. Create a new file and save it as metadata.yaml. Then, add the following:

---
title: Busy Doing Nothing
subtitle: 51 days from Canada to Japan
author: Rek Bell
publisher: Hundredrabbits
table-of-contents: true
lang: en-CA
rights: © 2021 MyCompany, *your chosen license*
documentclass: book
...

**NOTE: The three most commonly used standard document-classes in TeX include: article, report and book. Different document-classes have different default settings. The first time I published a book I omitted adding a document class entirely, and the text renders fine. Adding a "book" class will add settings that make the text more pleasant to read, like it'll align text on either the left, or right, to account for the book binding, it'll also add the chapter name at the top of the page.

The text in the .yaml file need to be delimited by a line of three hyphens (---) at the top and a line of three hyphens (---) or three dots (...) at the bottom. Metadata will be taken from the fields of the YAML object and added to any existing document metadata. See more about metadata files. Next, pass it to Pandoc as an argument:

--epub-metadata=metadata.yaml

Book cover: To add a cover, save the file to the folder with the rest of your text, and pass it to Pandoc as an argument:

--epub-cover-image=cover.jpg

The final Pandoc command to convert a file from Markdown to EPUB would look like this (with variations, depending on the extensions you choose):

~pandoc filename.md --from markdown+simple_tables+line_blocks --toc -V toc-title:"Table of Contents" --toc-depth=2 --epub-metadata=metadata.yaml --epub-cover-image=cover.jpg --css epub.css -w epub -o filename.epub

Test your book on a variety of devices before publishing it.

MOBI

Pandoc cannot convert files to MOBI, but it's possible to convert it using Calibre. To start, make an EPUB (steps above). To find out how to install Calibre, read my tutorial.

Run the following command in the terminal:

ebook-convert "input_file.epub" "output_file.mobi"

input_file is the input and output_file is the output. Both must be specified as the first two arguments to the command. It's possible to add more options to further change the look of the output file. There are too many options to name here, but all are listed here.

Calibre doubles as a book viewer, so you can test your book on that. Note that like with an EPUB, test the file on as many devices as you can.

Now, all that's left is to publish your e-book! I personally choose not to use Amazon, and publish on itch.io. There are no publishing fees, and with it, it's possible to automate uploads using Butler (itch.io's command line tools) if say, you want to publish changes to your book fast.

I have published the book from this tutorial, busy doing nothing as a paperback book. I printed using Lulu, a print-on-demand service. See it here(Lulu.com link).

If anyone is interested in me writing about this let me know, and I will. Also, if you've read this, and have questions don't hesitate to ask me! I'll do my best to help.