After writing and launching a technical ebook, I've had a few people ask me about the tools I used in the process. Instead of answering individually to everyone, I thought I would document the entire process here and send a link out instead.
The Big Picture
It's easier to talk about the entire process by breaking it down into three different stages: the input, the pipeline, and the output.
Input is the source code of the book - basically the inner content that the readers end up reading. The Pipeline is the process I used to generate the final artifacts ready for distribution. And the Output is how those artifacts end up in the hands of the readers.
Let's look at them one by one.
The Input
At its core, the book is a bunch of plain-text Markdown files.
~/W/p/personal-finances-python main ❯ tree book/src/
book/src
├── 00-about.md
├── 01-introduction.md
├── 02-plain-text-accounting.md
├── 03-beancount.md
├── 04-workflow.md
├── 05-testing.md
├── 06-reporting.md
└── 07-closing-thoughts.md
0 directories, 8 files
Each chapter is its own Markdown file. There are some code samples and images that these files reference which are also baked in to the final artifacts. But when it comes to the "source code" of the ebook, that's about it. Nothing special there.
I really like Markdown because (for me) it strikes exactly the right balance between size and expressiveness. The language is simple and small enough that you don't have to make a lot of effort keeping the syntax in your head. This is in stark contrast to something like RST where it's really hard to remind yourself what primitives produce what output. At the same time it's powerful enough that you don't feel like you can't express something - at least most of the time.
Because of this reason, most of my writing for the past few years has ended up being in Markdown. So that's what I ended up using for the ebook too.
The Pipeline
This is the slightly more interesting part where I have both good and not so good things to say.
I used a program called pandoc to convert the Markdown files into PDF and ePub files. Pandoc is a swiss-army knife of document conversion. You can take a document in one format and have pandoc convert it to a different (supported) format by passing it through pandoc.
In my case, the input format was Markdown and the final output was PDF and ePub. While the ePub conversion was a breeze, the PDF formatting took quite some time to get right (more on that later).
The good
Pandoc is extremely powerful. The process of converting documents from one format to another using just one command sometimes felt like cheating.
The manual is also very useful and comprehensive. In my experience, if Pandoc is capable of feature X, it's extremely likely that you'll find it in the manual.
The package is relatively straight-forward to install on most UNIX systems. For PDF generation, you'll most likely have to install a TeX distribution in addition. If installing TeX using a package manager is not really your taste, there are also official docker images that you can use.
Pandoc also supports filters which lets you do useful things with the output. For instance, I used the pandoc-fignos filter to add numbers to figures and reference them in the document. This was really useful to have text in the PDF link to the image.
Lastly, pandoc has been around for quite some time and has seen quite a bit of usage. This means that if you're running into an issue, it's very likely that someone else already ran into it so there might be a relevant Github thread or a StackOverflow question, maybe also with a solution. This makes it easier to get a headstart in case you're stuck on something.
The not so good
The not so good was mainly getting the PDF formatting right. Like I mentioned before, the ePub generation was a breeze. But getting a presentable PDF was a massive pain.
At its core, Pandoc is a document converter. It's not an ebook formatting tool. This means that while technically you can generate ebook PDFs, Pandoc doesn't know that it's working with an ebook (unless of course you're generating an ePub file).
This means that the default PDF output is really plain / bland. If you want the formatting to look a certain way, expect to spend some time and effort to get things running. In my case, I ended up spending days looking through the pandoc manual and searching for the web to fix specific formatting issues I was running into.
How do you properly insert a cover image at the front? How do you format blockquotes so they look a specific way? How do you specify the header and footer texts? What all listings settings do you need to adjust so that code blocks look good and consistent with inline code?
These are all questions I wish I wouldn't have had to spend time figuring out answers to. But unfortunately I did. If you're proficient with LaTeX, you might have a different experience because pandoc uses LaTeX to generate PDFs from Markdown. However, the last time I touched LaTeX was about 7-8 years ago so as of this writing, I wouldn't really call myself proficient there.
So almost every single issue I ran into was a bit of a pain. I would do an online search, find a solution, which was often in the form of a LaTeX snippet which I was supposed to put in the original source's preamble. Over time, all those LaTeX snippets added up and it became really tricky to figure out if a new issue was because of some weird combination of the existing snippets or some other reason entirely.
At some point I gave up trying to fine-tune these settings by hand and started looking for a boilerplate instead. In hindsight, this should have been step 1. 😁
I found an excellent Pandoc / LaTeX template which I ended up using for my ebook. This almost instantly solved all the formatting issues. If you're writing an ebook and are planning to generate a PDF using Pandoc, I highly recommend this template. Most of the formatting issues you could care about can be controlled using variables in this template. And the final output looks very nice.
The Output
There's honestly not much to write in this section.
I chose Gumroad to distribute the final ebook artifacts and I really like them. 😀
Gumroad is an excellent service which lets you sell digital products. It's mostly intended at online creators. Whatever product you want to sell, you can upload it and set up a product page for it, and can start selling immediately. You can get paid using either a PayPal account or direct bank transfer, depending on the country you're living in. And they even take care of handling taxes for you.
If you're considering selling a digital product, make sure to give them a try.
Conclusion
That's about it! I think those are pretty much all the technologies I used to build and sell my ebook.
If there's anything you'd like to know more about, feel free to @/DM me on Twitter!