Skip to content

Instantly share code, notes, and snippets.

Last active June 4, 2024 20:23
Show Gist options
  • Save caseywatts/3d8150fe04e0d8462cfc4d51b9856d39 to your computer and use it in GitHub Desktop.
Save caseywatts/3d8150fe04e0d8462cfc4d51b9856d39 to your computer and use it in GitHub Desktop.
Self-Publishing via Markdown

short url:

my book is out! an applied psychology / self-help book targeted at developers: Debugging Your Brain

Markdown --> PDF (as a booklet!)

Markdown --> EPUB and MOBI

I'm working on a book, "Debugging Your Brain" which I plan to self-publish. I'm writing the chapters in Markdown, and I want to have it both printed on paperback and available as an eBook on Kindle etc. Here are the tools I used to get my markdown files (from my Jekyll based blog) into the PDF, EPUB, and MOBI formats.


  • pandoc is a command line tool used to convert from certain file types to other file types
  • latex is a typesetting language / software used to make pdfs. I've seen this used most often in academia that uses equations, like math, physics, and computer science classes in undergraduate.
  • epub is the standard eBook format. As far as I've seen, this is used by everything except Kindle.
  • mobi is Kindle's eBook format. We'll use kindle's command line tool to convert an epub to mobi.

Pandoc Setup

pandoc is the main tool to convert markdown to other things.

Here is their official page with installation instructions:

My Linux Setup

To install an older version just to get you running:

sudo apt-get update 
sudo apt-get install pandoc

To install a more recent version instead, copy the url to the latest .deb package from THIS PAGE and download and install it using something like this:

curl -L > pandocinstaller.deb 
sudo dpkg -i pandocinstaller.deb

Amazon Self-Publishing

Amazon Royalties: 

first set up pandoc (above)

Markdown to eBook

To get your markdown into an eBook format, you'll first convert it to epub which pandoc can do on its own. Many eBook readers can use epub directly. To make a file compatible with Kindle, you'll then need to convert the epub file to mobi using the kindlegen command line command.

Markdown to EPUB

pandoc -o BOOKTITLE.epub -f markdown_github -t epub

Markdown to MOBI

Update: The command line method below is not working for me lately, so I am using the Kindle Previewer app for conversion instead.

Kindle needs mobi files. You can use the kindlegen command line command to convert epub to mobi. I got this download trick from this article, and the single-file-extract trick from this article.

  1. Get the most recent download url for the kindlegen "Linux Download" from the kindlegen webpage.
  2. Download, un-tar (unzip), and move the executable to /usr/bin so it will available as a command.
curl KINDLEGEN_DOWNLOAD_URL | tar xvz kindlegen
sudo mv kindlegen /usr/bin/kindlegen

Confirm you have it by restarting your terminal and running:

kindlegen -v

Managing Custom Kindle Content

  • You can add these .mobi files to your kindle device by emailing them to an email address Kindle gives you on the settings page.
  • You can remove old drafts via Amazon in the browser under "Content and Devices." Emailed files are not under "books" which is the default view, but under "docs."

first set up pandoc (above)

Markdown to Printed Booklet

Getting the pdflatex command

To use pandoc to generate pdf you must have the pdflatex command line command installed. The easiest way to get that is through these texlive packages. I got this trick from this github gist.

sudo apt-get install texlive-latex-base
sudo apt-get install texlive-fonts-recommended
sudo apt-get install texlive-fonts-extra
sudo apt-get install texlive-latex-extra

If these succeeded you should see a version number when you run this command:

pdflatex -v

Example PDF Command

pandoc --output OUTPUT_FILE_NAME.pdf  --from markdown_github+yaml_metadata_block --to latex
  • --from: If you are using markdown pages from a Jekyll blog site, these files will be a combination of markdown_github and yaml_metadata_block, and we can combine these with the +.
  • --to: to make a pdf we're using latex as our intermediary
  • --output: put your destination file name here. If you want it to be a pdf, make sure the extension is .pdf. For troubleshooting, you can change the file extension to .tex to see the intermediary LaTeX file that's used to make the pdf.

LaTeX Configuration  

The main reference for this is Pandoc's PDF creation documentation.

You can put LaTeX configuration in the yaml frontmatter block in the first file, and this will apply to all following pages as well. The frontmatter needs a --- at the top of your file, your context after that, and then another --- after, just like Jekyll blog posts. I opted to have a separate file for just this configuration versus having it at the top of my first chapter, but that's up to you.

Gotcha: make sure your pandoc command's --from contains BOTH markdown and yaml frontmatter (see above).

LaTeX Booklet Settings

To get latex to export to half-sheets, here are my yaml frontmatter with the booklet settings. I got some tips from this post. You can see the documentclass options visually on this blog post, and you can format them in yaml according to pandoc's Variables for LaTeX section. Passing options to the geometry package is interesting, because you have to pass "paperheight=8.5in" as a string with quotes, not as a nested key:value pair like other things.

title: Debugging Your Brain
author: Casey Watts
documentclass: book
- openany
- "paperheight=8.5in"
- "paperwidth=5.5in"
  • title and author go into the file's metadata as well as cover page
  • documentclass: book sets a lot of settings to reasonable ones for us (like asymmetrical margins to account for the book binding taking up space)
  • openany says that chapters can start on the left side pages as well as right
  • geometry settings here specify half of a "letter" sized piece of paper (folding the 11" side to be 5.5")

LaTeX Double Spacing

You may want to double-space the document for reviewers to write comments in. Add this to the bottom of your yaml frontmatter.

linestretch: 2

Adobe Booklet Printing

UPDATE: Adobe broke the ability to "print to PDF" from itself... If I had to do booklets today, I'd investigate the pdfjam tool for doing booklet formatting.

OLD ADVICE: Adobe PDF Reader has booklet printing built in! There is a "Booklet" setting under "Page Sizing & Handling". See more detailed instructions in this Adobe help article

Copy link

sleien commented Sep 1, 2022

The link to your website at the of seems to be broken it redirect me to instead of

Thank you for the nice doc!

Copy link

The link to your website at the of seems to be broken it redirect me to instead of

Thank you for the nice doc!

Thank you! Fixed it 😄

Copy link

I haven’t tried it yet, but this tool pdfbook2 looks useful for booklet printing!

Copy link

vcarl commented Oct 26, 2023

Cheers for this! Someone asked directly about self-publishing and I was glad I had this bookmarked to share

Copy link

Nice writeup! I have been on this journey as well. A few tips or alternatives:

  • To get all of the LaTeX installed with pdflatex, I install the texlive-full package. It takes long time. I ended up making a docker image so I don't have to install it. Here's the Dockerfile I use which installs other stuff that I ended up needing, namely:
    • Fix locales
    • Install pygments for code syntax highlighting
    • Graphviz
    • Fix some meta files for ImageMagick to allow it to deal with pdfs
    • Node is installed because I use puppeteer to take screenshots - it's not required to do pandoc/LaTeX.
  • I've found you need to run pdflatex twice in a row to make it find all cross-references properly. You have to do it a third time if you are creating an index (which requires running makeindex between the second and third runs). This may be apocryphal, but it does work.
  • On that note! Markdown xrefs were really hard for me to get right, so I ended up doing stuff like check out [this figure](#some-figure)<span class="latex-only">on page \pageref{some-figure}</span> and then hiding .latex-only in the epub css file. Probably not useful if you aren't doing a printed version with page numbers.
  • I documented some details about some e-readers on my website Important things to know as an author:
    • MOBI is dead - Amazon has or is about to kill it.
    • Kobo is extremely degenerate in the formatting it supports. In particular you have to embed a monospace font into your epub if you need that.
    • Kobo is extremely slow to open docs and turn pages compared to even an ancient Kindle. I forget the option, but pandoc can split up your ePub into many small .xhtml files, which improves things on Kobo. Kindle doesn't care.
    • Kindle has the best reading experience in terms of supported HTML rendering and stuff.
  • I personally find e-readers to be horrible reading experiences, so I'm trying out including additional PDFs in my bundle that have no margins and use larger fonts (in addition to the epub of course).
  • I use SendOwl for selling the e-books as it's very cheap per month - you end up only paying the Stripe fee on each sale.
  • I also sell the Kindle-only version through Amazon since I figure it may result in sales that might not happen if people are on Amazon. I price the Kindle-only version there slightly lower than on my website to avoid Amazon issues (and because just getting the Kindle version is less valuable than getting the files)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment