Tuesday Tooling - Make ebooks from markdown with Pandoc

by Les Pounder

In the middle of a pandemic, I start using Pandoc. The two are not the same.

So what is it?

Pandoc is a universal document converter..

"If you need to convert files from one markup format into another, pandoc is your swiss-army knife."

Pandoc can convert from one format to another and it can be used with

  • Markdown / Markup
  • HTML
  • Ebooks
  • LaTeX
  • Word / Open / Libre Office
  • Jupyter notebook
  • Wiki Markup
  • Slideshow
  • PDF

In this post I shall be converting a markdown file into an EPUB book.

Hi reader!

I never put my blog posts behind paywall or pop ups because quite frankly that is annoying and prevents anyone from accessing the content. I will always keep my blog content free of charge. But I do ask that if you are able and willing, that you buy me a "coffee" as it helps me to pay for hosting this blog, and to buy stuff to hack from Poundshops / Dollar Stores / Aliexpress which are used in free projects and reviews on this blog. It is You dear reader who make this possible, and I am immensely grateful for your support.

Thanks!

So how do I install it?

Windows

I installed Pandoc on my Windows laptop by downloading the msi installer from their website.

For Linux users

Pandoc is available from your repository.

For Mac users

There are a few different ways to install, a popular method is via homebrew.

brew install pandoc

So how do I use it?



First I'll check that pandoc has been installed correctly. In a terminal / command prompt I type the following to check the install by printing the version number.

pandoc --version

The source material



To create the book I raided an old blog post, my TinyGo for Arduino post. I opened the post in the editor and copy / pasted the markdown into Notepad++.

I added a few extra lines at the start of the file, for my book title and author name.

% Friday Fun Collection
% Les Pounder

I then went through the file and removed any embedded web content, and I edited the file to change the links used for images. On the blog they are relative URLs, but for the ebook I need them to be local files. So I changed the links to just the filename.

For example

/content/2020/03/cool-image.jpg
becomes
cool-image.jpg

Preparation like this is important, as the source material was originally a blog post it had many embedded items, which needed to be removed.

Creating the ebook



With the file prepared and ready for conversion, I opened a command prompt and navigated to the folder containing the file and images.



Then in the command prompt I gave the command!

pandoc mybook.txt -f markdown -o mybook2.epub

I call pandoc and then give it the name of the source file mybook.txt. Next I tell pandoc that the file is markdown -f markdown. Finally I tell pandoc the name of the output file -o mybook.epub.

All being well the command will run with no errors or output. Any errors will appear in the command prompt, typically these will be dead links.

Reading the book



To give the book a quick read I installed calibre, an ebook management and reading tool. I have used calibre on Linux machines for many years, to organise my collection of tech and maker ebooks.

I imported the book and was able to read it :)



But I wanted to read the book, so I converted the EPUB file into a MOBI file using an online tool

Note: I'll be looking into doing this using pandoc or a local / offline tool



Then I sent the file to my Kindle and I saw my book was there!

Final thoughts



Pandoc did not like it when I tried to directly convert the markdown to MOBI

My process is by no means perfect, and I still need to fix formatting issues and tinker with how pandoc works. I would like to convert the markdown into a Kindle MOBI file as part of pandoc, rather than relying on online tools. But for less than 3 hours work and research, I am happy with this initial effort.

Happy Hacking!