🧰 Epub Tools
In my quest to find some additional reading material, I was inspired to scratch an itch over the weekend that has bothered me for quite some time. For over a decade Wizards of the Coast has consistently released web-based episodic fiction to accompany their Magic the Gathering set releases. This is awesome because these stories add a lot of depth to the cards and characters, but it's always annoyed me that they've never been compiled into ebooks. I just don't prefer to read fiction in front of one of my computers so I haven't read as many of these stories as I would like.
Over the weekend I decided to take a stab at solving this issue1. The open source command-line utility pandoc makes assembling an epub relatively simple if you provide a collection of markdown files. The stories are all individual web pages and Brett Terpstra has created an awesome utility called Heck Yes Markdown that I put to work for the html → markdown conversion process2. I also downloaded all the inline png images to a local folder and manually converted them to much smaller webp files using Acorn. I did some light editing on the markdown files to remove some unnecessary cruft and changed the image links to point to the local webp versions. I used Marked 2 to inspect the markdown rendering for my documents and then I ran the build.sh shell script I created to tell pandoc how to assemble everything.
Early in my process I mostly tested directly in Apple Books on my Mac and iPhone every time I added an additional story episode, but this proved inconvenient at times because of the delete and transfer process. Later I tried out an open source cross-platform epub editing app called Sigil that is really helpful for directly inspecting, viewing, and modifying epubs. I also made things more challenging by deciding to use a tweaked version of the Amblin theme in Marked 2 for my epub layout. That particular css theme relies on a wrapper class so I had to provide a slightly customized epub rendering template to get it to work properly in pandoc.
After a lot of trial and error, the resulting epub for the new Aetherdrift set had eight chapters, 269 iPhone 11 screen-sized pages, and 46 images while checking in at 5 MB. This ended up being a really good learning exercise for working with pandoc's epub support and something I'm sure I'll continue to put to use for my own projects 3. Long term I'll probably continue making epub versions of recent and old MTG set stories as necessary for my own use as well unless Wizards starts releasing official ones.
This post is going to be a broad overview of my initial solution without fully delving into specifics. There's also tons of room for further automation.↩
Page → Marky MMD being the option that worked best—the versions with Readability trash a lot of important punctuation.↩
Yearly blog archive epubs could be fun.↩