I’ve been reading a lot, from materials that are interesting to ones that are not so interesting. I’ve read so much that I ended up with enough material to compile into a manuscript a bit larger than what a blog post could handle, unless I published a massive number of posts to contain everything. We’re talking about 10,000 words or more.
Actually, let me put this on the list:
- Build a web component that counts the words in my articles.
And what did I learn from writing a book? A lot, and I’ll explain in more detail what it’s like to write a book, or in my case, an epub.
Step 1: Writing
If you have nothing to write, just write. Put ideas on paper, put ideas anywhere, and then use the power of an LLM to see how topics connect. Why use an LLM for that? Because it’s a natural language model, it was made to calculate text and predict the next word, and of course, it can be very helpful when writing.
Alright, now that we have some text, we need to organize it. I’ve become something of an open-text evangelist, aka: text I can open in any editor. Not because I’m a purist, but because I think using neovim to write text is a useful idea. And of course, it means fewer transformations for the next steps.
What’s the best way to write text then? Honestly, I don’t know, but I think writing in Markdown (md) is a great place to start. I was even ready to learn LaTeX to write, but I couldn’t find a clean and simple way to convert LaTeX into ePUB (epub).
Okay, text is just text, so why am I talking about how I organize and store it? Because writing something that should be as simple as “open Word and type” is actually way more complex. Maybe it’s because I’m a bit silly, but the truth is I want to write in a way that makes it easy to move the text later, and of course, iterate quickly from text to final product (ePUB).
Still, the question remains: What is an ePUB?
What is an ePUB?
According to Wikipedia:
EPUB is an e-book file format that uses the “.epub” file extension. The term is short for electronic publication and is sometimes stylized as ePUB. EPUB is supported by many e-readers, and compatible software is available for most smartphones, tablets, and computers. EPUB is a technical standard published by the International Digital Publishing Forum (IDPF). It became an official standard of the IDPF in September 2007, superseding the older Open eBook (OEB) standard.
Alright, but how do you write an EPUB? Just write?
As incredible as it may sound, yes just write. It’s basically HTML, as the next Wikipedia paragraph explains:
The Book Industry Study Group endorses EPUB 3 as the format of choice for packaging content and has stated that the global book publishing industry should rally around a single standard. Technically, a file in the EPUB format is a ZIP archive file consisting of XHTML files carrying the content, along with images and other supporting files. EPUB is the most widely supported vendor-independent XML-based e-book format; it is supported by almost all hardware readers and many software readers and mobile apps.
So you’re telling me that the famous HTML, originally created to organize and style text for use on printers, is being used here?
(I was going to link the Wikipedia page again, but I’ll let you think I’m talking nonsense so you can call me out when either of us is wrong)
So it’s like writing HTML, but let me ask you again: do you actually write HTML? It’s been a while since I wrote it directly, most of the time I use a parser and write in another format, then let the parser do the conversion. It’s just easier to write in something like markdown and then convert it to HTML. You see the point?
I used Markdown because it’s easier to convert to HTML, and then I can inspect it. Cool, right?
One pipeline after another
Alright, now I’ve got Markdown and I know what an ePUB is. Time to see how to convert one to the other. Because, like I said, I’m not going to manually write every <p> for the dozens of paragraphs in the book. So either I make a converter or find an existing tool. A quick search shows nothing useful and lots of paid solutions, like usual the enshitification already happened in this market.
Then I searched a bit more, and look at that, there’s a tool that converts one to the other. Actually, it’s super generic, and I can totally use it. Welcome to Pandoc. After a quick brew install pandoc, it’s ready to go. A super simple command: pandoc ./book.md ./book.epub, and voilà, the ePUB file is done.
A quick inspection reveals it’s just a basic zip file, with each <h1> heading split into a new section. Super simple and solves my problem. Believe me, this was just the beginning. Let’s make it more complicated.
One manuscript, two languages
English isn’t my native language, and I’ll definitely commit linguistic crimes writing in it, not just in blog posts, but also in the book. But still, I want to publish the book in both my native language (Portuguese) and in English. Even if it’s a side project to explore ePUB concepts, it’s a good way to make the whole process more visible, for me and for others.
So, I have manuscripts in both English and Portuguese. Now I need to run the conversion command twice. And if I forget? Well, time to write a bash script and automate my life.
A little bash and what could go wrong?
# make.sh
pandoc ./book-br.md ./book-br.epub
pandoc ./book-en.md ./book-en.epubBeautiful! Now I run one command and get both books. Can you feel it?
Images
I never intended to make an illustrated book, just a manuscript with a single cover image. Since I walk around a lot, I have lots of nice photos that I fully own the rights to. Best part? No people in the background, no houses, just parks and nature.
Alright. I can take one image, throw it into Photoshop Affinity Photo, tweak it (I’m colorblind, so balanced enough is my standard), throw a white title on a black bar, and done! A simple cover. Later, when I feel like it, I’ll make other covers for edition 2.
But I still don’t have a title. I wrote half the book, and I’m already thinking about the cover. If I change the title, I’d have to update it in Affinity. Nope, I need to automate this. I could build a basic HTML page to layout the cover the way I want, then generate an image from that. I don’t need an 8000-pixel width image, 1000 is plenty. How do I convert HTML to JPG? There must be a solution.
Right? There is, right?
A lost week
I wish I could say I found the solution in 2 minutes, but it took almost a week. This is a side project, and I’ve maybe a couple hours a day to spend in it, and it took the whole week. I ended up finding a pretty silly solution that works well enough: open a chrome --headless instance and take a screenshot. Crazy, right? But it works. So I use that screenshot as the cover.
Wait. For some unknown reason, there’s a white bar at the bottom. Fine, I adjust the browser window, nothing. Maybe it’s a CSS issue. Or my Chrome version. Maybe I should use Firefox or Safari. But why isn’t anything working!?
Okay, breathe.
I can crop the image, right? So I can use a CLI tool to crop it. I do recall manipulating images on the server, what was the tool? Let me introduce you to the most beautiful CLI in the world: ImageMagick (magick). This little tool is magic. I just needed to tweak my bash script a bit. With this I can to automate this, and it’s taking a week to do something that should take 5 minutes. But what if I edit the image after taking the screenshot?
# make.sh
chrome --headless ./cover-br.html --screenshot ./cover-br.png
chrome --headless ./cover-en.html --screenshot ./cover-en.png
magick ./cover-br.png -resize "x400>" -crop 1000x500+0+0 ./cover-fix-br.png
magick ./cover-en.png -resize "x400>" -crop 1000x500+0+0 ./cover-fix-en.png
pandoc ./book-br.md ./book-br.epub
pandoc ./book-en.md ./book-en.epubHold on, it’s getting repetitive. Let’s throw in a tiny variable and simplify:
# make.sh
LANGS=(
"en"
"br"
)
for lang in "${LANGS[@]}"; do
chromium --headless --screenshot=./cover-$lang.png --window-size=600,1000 ./cover-$lang.html
magick ./cover-$lang.png -resize "x400>" -crop 1000x500+0+0 ./cover-fix-$lang.png
pandoc ./book-$lang.md ./book-$lang.epub
doneI know some developers who would already be writing a Java app to solve what these few bash lines already do. With the image problem solved, it’s time to think about the next step, ISBN.
Give Me ePUB and I’ll Give You ISBN
Since I’m planning to first publish in my native language, I went through a Brazilian government platform to get the ISBN. And honestly? It was way simpler than I expected. I submitted the EPUB file, and two days later, boom — I had the code. Way easier than I imagined. I was fully prepared to lose another week on this part of the process, but nope — it just worked.
I think I’ll leave it at that for now, and soon I’ll figure out how to get the ISBN for the English version as well.
Why would I need a ISBN you ask? Getting an ISBN isn’t just about slapping a barcode on your book, it’s about claiming authorship. It officially marks the book as yours, with your name tied to that title in all the right databases. It’s the difference between I wrote a thing and I published a thing. Plus, having that ISBN means your book can be cataloged, sold in stores (digital or physical), and taken seriously by anyone who needs to look it up. It’s a small step that gives your work a legit identity in the publishing world.
And since we are talking about publishing…
Amazon and dystopia
Alright, since the first version I want to publish is in Portuguese, I’ll focus on the Brazilian market, maybe “Portugalian” market as well (I’m sure I butchered that word). Either way, I need to publish. First stop: Kindle, aka: Amazon.
How does it work? Surprisingly, they have a pretty streamlined publishing platform. It’s called KDP, Kindle Direct Publishing. Cool. Let’s see how it works.
Apparently, Amazon can give my book better visibility if I make it exclusive. I don’t like exclusivity, so I probably won’t hit that button. But the royalty rate? If I don’t go exclusive, I only get 35%. So for every 10 (whatever unit), I earn 3.5. Ridiculous, right?
But if I go exclusive, magically, I get 70%. So for every 10 sold, I get 7. Sounds nice, huh? But only if I’m exclusive to Amazon. And since I have so much love for my favorite CEO, I’ll just write a blog post like this one to vent my critique. You thought I was doing this for engagement? Nope. It’s a critique of Amazon’s absurd pricing.
Let’s check Apple, notoriously bad for selling anything. And look, Apple is super open: 70%. Every 10 I sell, I get 7. Beautiful. Now Kobo? Also 70%. Google Books? Same.
It’s funny how Amazon, with its massive monopoly, makes tons of money while forcing authors into exclusivity just to get decent royalties. And of course, they block other ePUB stores from competing. Wonderful, it’s like we live in a dystopia. And what can we do to change that? I’m doing what I can: sharing knowledge and explaining how I like to write in my terminal.
Final thoughts
So, what started as just reading a lot turned into a rabbit hole of writing, converting, automating, designing, and questioning the very nature of modern digital publishing. Honestly, I didn’t plan to write a book, much less two versions of it in two languages. But here we are, Markdown in hand, bash scripts running, headless browsers taking screenshots of HTML covers, and ePUB files popping out like toast.
If there’s something to take away from all this, it’s that creating and publishing a book today can be both ridiculously simple and unnecessarily complex, often at the same time. You can write with just a terminal and a text file, yet spend a week figuring out how to properly crop an image from a headless browser. That’s the beauty and the madness of doing things your own way.
I didn’t do this to be efficient. I did it because I wanted to understand every piece of the pipeline. From the words I write to the file formats, to the sketchy white bar on the cover image, to the very real dystopia of digital distribution, I wanted to see it all, break it, and rebuild it.
And if I can turn that chaos into something useful (or at least readable), maybe it’ll help someone else avoid a few headaches… or at least laugh at mine.
Now go write your book. Or don’t. Just make sure whatever you’re building, you’re doing it for the right reasons, even if it’s just to prove you can.
(() => {})()