Chapter structure

The examples on the Pandoc documentation used h1 Markdown headers (# headers) to denote new chapters, and all of my articles were normalised with h2 headers as the highest. Rather than doing anything special, I decided to just copy it out and find and replace ## with #, down leveling every header by one level. The docs also recommended splitting each chapter out into its own file and folder, likely to keep any images or other embedded media alongside the chapter that they’re referenced in. While my article didn’t contain any images, I opted to do this anyway. They also suggested prefixing each chapter's folder and file with an incrementing number, to ensure the chapters were referenced in the correct order. The following is a snippet of my folder structure I ended up with,

Styling tweaks

Pandoc lets you override the CSS of the published ePUB file, through the --css [file] flag. You can find the default CSS file on their GitHub, and then make changes on top of that to fit your needs. While I played around with this a little bit, I ended up sticking with the default. Maybe if I get the motivation in the future I’ll go through and borrow some of the styling from my website, such as the way links look.

While this specific post of mine was fairly simple, largely just being text, links, and headers, if you’re using anything beyond this you might need to make sure they actually display properly. Beyond just CSS, you might also need to tweak the style of Markdown you’re using. I needed to fix all of my relative links to ensure they were prefixed with my site’s hostname, and if you’re using any non-standard Markdown syntaxes for setting attributes such as image widths those might need to change too.

Metadata

The Pandoc documentation also mentioned a title.txt metadata file, to store various metadata about the book. I entered a title, subtitle, and my name, then set out to generate an actual ePUB file. I ran pandoc -o decade.epub title.txt ./*/*.md, and out popped my eBook.

Cover

The first thing I noticed, was that the early pages looked fairly weird in the Apple Books app on my phone. There were blank pages, weird spacing, and it all just did not feel polished. I assumed this was likely due to the lack of a cover image, so I created a quick mock one to add to the file. A few sources online told me that 1600x2560 was the recommended size for an eBook cover, so I went with that. Adding the --epub-cover-image cover.png flag to my Pandoc script, I now had a copy of my book with a cover, and absolutely none of the problems I found earlier were fixed 🙂.

Oddities

At this point I wanted to fix these oddities I was seeing in my book. I opened the file in Sigil and couldn’t find any of these blank pages that I was seeing. Everything seemed to be completely normal. I then downloaded a random ePUB reader for Windows to try it with another reader application and found completely different spacing issues and blank pages.

For context, I’m not someone that’s read many eBooks. I read so many books as a kid, but all were physical printed books. eBooks weren’t much of a thing when I was growing up. My reading habits have sadly dropped off as an adult, so I haven’t had too much eBook exposure, and the few that I have read have all been by the same author (Stephen King). I’m telling you this mostly to get across the point that I am not familiar with what eBook readers expect, so I was completely shocked when I researched this online and found that eBook readers “just do that.”

Apparently, it’s common and normal for eBook readers to opinionatedly insert blank pages into books. Different readers insert different blank pages around ends of chapters, before new chapters, throughout the opening pages of the books, etc. These issues I was encountering were due to me wanting to have more creative control over how the eBook appeared than the creators of these applications wanted me to, apparently.

Maybe there’s a way to fix this, but I couldn’t find one in my research that didn’t have side effects that affected other eBook readers inversely. In the end, I decided that I just had to live with it. It’s not like I didn’t have to flip past multiple blank or regulatory pages in the physical books I’ve read, it just feels worse on an eBook because you can’t physically see the rest of the pages. Either way, I’d already spent too much time on this and didn’t want to waste much more. I assume if you did want to work around this to a larger extent than I did, you could create separate eBook files per platform and just design them for the most popular reader application of each.

ISBN

First up, I wasn’t sure if I needed an ISBN. A fair few sites said if I was exclusively publishing to Amazon then I didn’t, but I intended to publish to other sites. Given this in all likelihood was going to be the only book I ever published, I decided to get one anyway to get more of a real author experience, and to make it easier if I did end up needing it in the future. I don’t recall if it ended up being strictly necessary, although it was definitely something I was able to enter into the different publishing platforms.

I purchased an ISBN and then found that the ISBN registry requires a bunch of information about the book similar to each publishing platform. Out of all the platforms, this was probably the one that took the longest to fill in, as it required the most data. From what I can tell, submitting the information here allows it to be found by searching the ISBN database. However, as of writing this article multiple weeks after setting up the ISBN, I still cannot find it in various database searches. I’m not sure what’s up with that, maybe it’s just a really slow propagation process.

Google Play Books

Out of the actual publishing platforms I submitted to, I opted to go with Google Play Books first because I was anticipating it’d have the most issues. Despite the normal reputation Apple has, I’ve always had more trouble submitting Android apps than iOS ones. On top of this, I’d recently had my Google Play apps account deleted by Google for “failing to verify my email address,” despite having done that and having proof that I had done that.

Overall, the process was fairly straightforward, albeit with a long review process. I believe there was a public holiday in the US during my review period, so the review itself ended up taking around 9 days, by far the longest of any of the platforms. My ability to actually setup my book and submit it was also delayed by a few days, due to an issue where the platform would error when I tried to create a payment account. I submitted a support ticket which resolved the issue.

Out of all the platforms it looked the most modern and generally worked the best, although the backend APIs felt fairly inconsistent and error prone. If I was publishing another book, this is probably the platform I’d have the most faith in actually working, assuming Google don’t decide to randomly delete my account before then. As my only issue occurred during account setup, and the lengthy review process was for new accounts only, I feel it’d be fairly straightforward to make another book on here.

Amazon Kindle

This was the one I was the least familiar with, having never owned a Kindle or used Amazon for anything outside of consumer purchases (and AWS, although I feel that’s an entirely separate division). Overall, it was by far the simplest to setup, however it’s the one I’m overall the least happy with the outcome of.

Firstly, no matter what format I uploaded my cover image in, it always ended up looking extremely compressed to the point of borderline illegibility. How well the covers looked did differ per platform, and each platform required a different format, but Amazon seems to do something after the initial upload that turns it into a mess of JPEG artefacts.

Secondly, they don’t allow you to give a book away for free. I’m not sure why this is, and I understand that offering a place on their store is a service that I get for free so they’re allowed to try recouping something for that, but it entirely prevented me from using Amazon for my book as I wanted it to be free. There were some workarounds mentioned online about having them price match it with Google Play Books, however as of writing this article that hasn’t worked. I hope they change this in the future, but given there have been complaints about this exact issue for over a decade, I’m not hopeful.

Apple Books

As I’ve overall had the best experience with Apple’s app store submissions in the past, I left this one for last. I expected it to be the simplest, or at least that I’d be familiar enough with its quirks that it wouldn’t be that complicated. Wow was I wrong. There are parts of this process that I wouldn’t even feel comfortable shipping in internal tooling in a workplace.

I started in iTunes Connect, setting up a book publishing account and filling in the various agreements. This process wasn’t new to me, as app submissions were through iTunes Connect prior to Apple splitting it out into App Store Connect. This process went fairly smoothly, until I tried to actually setup the book. I couldn’t find a button to add a book. Turns out, I needed to go to an entirely different site that allowed submitting it via an interactive form. I ran into a few odd hiccups with data validation in the form, but it didn’t block me too much.

Once my book was available to edit within iTunes Connect, I ran into another problem. No matter what I did, it would not let me fill in the regions and prices that the book was meant to be available in. I’d press the submit button after filling in the information on the “Rights and Pricing” page, and then it’d give me a blank page. Upon inspecting network requests, I found that it was trying to show me a generic 500 error. I tried across a few different devices and browsers. Chrome, Edge, and Firefox on a Windows machine. Safari on an iPad and an iPhone. Chrome on a MacBook Air. None of these worked.

So, for the second time in this eBook publishing odyssey, I was creating a support ticket. A few days later, I was asked by a support agent to send in a screen recording of me going through the process that was erroring, using Safari on a Mac. I gave this a go, and miraculously, it worked while using Safari on a Mac. I tried again on the other browsers and devices, all failed. So somehow, this simple web form submitting simple data, only works when using Safari on a Mac. Not Safari on an iPad, or another browser on a Mac. Only Safari on a Mac.

Maybe there was some slight encoding difference that the backend server was extremely sensitive to, but that honestly left me shocked. When looking up the Apple publishing process in self-publishing communities, the recommendations are always to use software that automatically publishes to multiple platforms rather than trying to publish to Apple yourself. I can see why. Once I got past that hurdle however, everything was fairly simple, and the book was available on the store shortly after.