Publishing EPUBs with Pandoc

This is not a recommendation to make EPUBs with Pandoc. If you're going EPUB first, do not start with Markdown and Pandoc. Use literally anything else. I use this method because I write paperbacks first, and need to bodge something together to turn things into EPUBs.

This is a blog post about the second worst experience a self-published author can have.

I mainly use Typst for all my PDF generation. I like it, it's simple, powerful, and it's easy to make things that look great. I use it for things that are not PDF generation, like making the layouts and frames for Bloodless cards.

This does come with a small problem. Typst doesn't support EPUB export yet. It barely supports HTML. So when my paperback is ready to publish, I have an entire separate manual process to work through. It's not too bad, but it's a little bit of tedium. In this post, I write that process in case anyone else uses Typst for publishing books and realizes they should probably make an EPUB too.

I should start by saying that it's best to do this once your Paperback is published. So published in fact that you can't take back anything about it. Including the typos.

So, the first thing I do is divide the file into chapters. You can also copy the entire content text into a single markdown file, as the file will get split into multiple anyways. If you have content that's supposed to appear before the heading, there is nothing you can do. Pandoc sucks ass. I am looking into other ways. This is what I've got in the meantime.

I make sure to replace Typst headings for MD headings.

Then start looking for the character # in text sections and replace it for an equivalent HTML tag. If it doesn't exist, make css file to style it. Style it right away. CSS and HTML can be finnicky and you might need more than just a <div> with a class. Make sure it's reusable, even if you don't reuse it in your book. You might reuse it for other books.

Some things you might want to do:

• Use an empty div height CSS property to add spacing.
• Use an div with this CSS for making content that takes up a whole page. This will also center it, but you can remove all that:

  .page {
      min-height: 100vh;
  
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: center;
  
      text-align: center;
  
      break-before: page;
      page-break-before: always;
  
      gap: 1em;
  }
  
  .page > * {
      margin: 0;
  }
  

When doing font stuff, make sure to explicitly include your fonts folder with --epub-embed-fonts. This should be a glob to your font files, not a simple path to a folder with fonts. Your CSS should refer to your fonts as being inside ../fonts/.

After this, I'm basically done with all the manual editing. Now I just make a metadata.yaml file.

I typically put the pandoc command inside a justfile so I can just make it. Here's my justfile for Heaven Reaches Out to Us.

make:
    pandoc \
        ./metadata.yaml \
        ./dedication.md \
        ./foreword.md \
        ./chapters.md \
        ./afterword-acknowledgements.md \
        ./aboutme.md \
        -o book.epub \
        --css=style.css \
        --toc \
        --embed-resources \
        --epub-embed-font=fonts/* \

If you buy the ebook, you'll realize I didn't do the cool thing where the Acknowledgements and Afterword shared a page. This is because that sort of thing is not possible with this method. I know the concept of a "page" is ill-defined in EPUBs, but come on, at least they could share a file? I hate Pandoc so much.

Also, if your original PDF source code calculates things for you and those thigns go into content you're gonna have to hardcode all of them.

It's not the best way to do things. It's honestly probably the worst way. To do anything. Ever. But it's what I do right now and I can do it in one morning if I really feel like it. I don't recommend anybody do this, but if you're desperate I hope this blog post helps. Once I find something that is actually good I'll make a blog post too.