By the time you are reading this, my several-year-long journey in book writing has neared its end. My first book, Mise en Mode, is now available for purchase. Now that it’s complete, I wanted to document some of the process so that you might consider venturing out into the great unknown of self-publishing a little better than I did.
How it started
After speaking on the subject at Clarity in 2023, the topic generated a great deal of interest. I received lots of questions and people who wanted to know more. As per usual, I sat down and started writing another blog article here. But after looking at the reading time showing 15 minutes, not being anywhere near done, I felt it was time to go to the next level.
I’ve always been interested in writing a book. I have a few books on writing books. Though I never had a topic that I felt passionate and knowledgeable enough to write about. I know they say that just because someone has written something before, there’s no reason not to write about it again, but I wanted to be unique with whatever my book was about. Mise en Mode was most certainly that opportunity.
Where to write
The next hurdle was where I was supposed to put these words. I did some research here, and even spoke with Ethan Marcotte early on about his process. My big worry was, “if I start writing in X, will that make it easy to turn into a physical book?” The answer was one of the hardest parts of the process.
I first started writing in reedsy. Its main selling point is that you will absolutely get a printed book using their platform. Additionally, it’s a web-based editor so I can write anywhere. I actually tried to use reedsy twice, thinking that the shortcomings could be overlooked. The reality is that reedsy is not suited for technical books. It can’t support inline code and to speak about design tokens, there’s a lot of inline code. I figured if you’re writing something non-technical, this would be a good place to try.
So from there, I searched for something that was more suited for technical writing. I saw some reddit posts that claimed the publishing houses might expect AsciiDoc as a format because they already have templates to render that format into a book. From the look of the syntax it was markdown-like which was good. I preferred to write in markdown because I’ve been using it for years and it streamlines the content management process. I could also write and version control using GitHub so I could even edit in GitHub directly. The syntax isn’t really markdown, it’s a bit different but not too far from what I was used to writing.
It’s been a while and I don’t remember the specifics but I ended up having problems rendering the final book using AsciiDoc. I know you need to install a few things in order to get it working, which I don’t really like. I think the biggest problem was customizing the final output to something that looked like a real book.
That caused me to go out and look for other solutions. I’ll also say there’s a lot of red herrings out there. For example, the first line of mdbook says:
mdBook is a command line tool to create books with Markdown.
But when you read the next line, it’s clear this isn’t what I want:
It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation.
It should be called mdDoc or mdWebpage.
I eventually found Quarto which has a syntax even closer to markdown. I even tried rendering what I had as a book and at first glance it seemed like everything worked well. I ended up writing the entire rest of the book in Quarto.
Then, came the rendering.
Even though I had sent a first pass through, it was where you look at the details. What I found was snag after snag. Quarto uses LaTeX and pandoc to render documents. LaTeX for the formatting, and pandoc to convert to a specified output. If you touch nothing, this works well enough. But if you need anything special, you are in for a challenge.
One of the things that really caused me to throw out this toolchain was line wrapping. The token names in the book are long. For example $action_primary_backgroundColor and because of this I expected the inline code to wrap when necessary. Otherwise, you’d get huge distracting gaps in the text. You might even be seeing this awful lack of wrapping in this very post! I’ll fix it here, eventually…
However, for a printed book where I could curate how it looked precisely, this was unacceptable. However, no matter what I tried, I couldn’t get LaTeX to make these wrap. There were plenty of other problems like when to make pages break. I’d have code blocks and callouts broken between pages. I couldn’t believe how hard this was, or how this wasn’t just something built into the system. Why would it be acceptable for a code block that isn’t larger than a page to split between pages? I said to myself, I know exactly how to do this in CSS.
One last attempt was to try and make this work using Adobe InDesign. My wife worked in publishing before and was familiar with the features of the program. However, what made this a non-starter was the restrictions on the callouts. Because the callouts are in their own colored boxes, they can’t be given styles like the normal paragraphs. My wife was trying to hack together something to make them look good enough, but at this point I didn’t want good enough. I wanted it to look like I expected it to look and I wanted it to be easy so if I needed to make an edit, it wouldn’t break the entire layout.
CSS to the rescue
Toward the end of my frustrations with book layout, I couldn’t stop but think to myself “Why is this so hard? I could do this in CSS in minutes!” That’s when I went out to see if anyone actually did do this. That’s when I found this post by Ian McDowell where he outlines how he used CSS to layout his print book. He even shows the result at the end which was very inspiring.
So, that’s exactly what I did. While I’m normally an Astro fanboy, I decided to use 11ty for this because all I needed to do was convert markdown to HTML and 11ty is made for that. Then I could just write CSS as I normally would, hit Ctrl+P on my keyboard and save it as a PDF. There’s actually not much more to it than that, but I’ll go over the items that are unusual.
In my book I set up the following values:
:root {
--page-size: 6in 9in;
--page-margin: .75in;
--inner-margin: calc(var(--page-margin) * 1.5);
--runner-margin: calc(var(--page-margin) / 2);
}
The --page-size is used in the @page declaration directly, along with the --page-margin to go around each page:
@page {
size: var(--page-size);
margin: var(--page-margin);
counter-increment: page;
}
That counter increment property is described in an earlier post that helps create page numbers. Next, we need to increase the inner margin on the correct pages.
@page :left {
margin-right: var(--inner-margin);
@bottom-left-corner {
font: var(--font-caption);
content: counter(page, false-start);
margin-block-end: var(--runner-margin);
}
}
@page :right {
margin-left: var(--inner-margin);
@bottom-right-corner {
font: var(--font-caption);
content: counter(page, false-start);
margin-block-end: var(--runner-margin);
}
}
The runner is the bottom of the page and this is a bit larger to make room for the page numbers. Finally a few other items to help with printing:
body {
-webkit-print-color-adjust: exact !important;
print-color-adjust: exact !important;
}
The print-color-adjust: exact is used to tell the browser that these styles are made for print and to not make any opinionated changes to the page. Without it, the print rendering could look unexpected by removing background colors for example.
From there, we have a few additional properties that help. For example, here’s all of the items that I want to avoid a page break:
:where(ol, ul, table, figure, pre, blockquote){
break-inside: avoid;
}
For headings, I have slightly different rule.
:where(h1, h2) {
break-before: right;
}
:where(h3, h4) + * {
break-before: avoid;
}
For h1 (part titles) and h2 (chapter titles), I want to make sure that they always start on a right-hand page. That’s what break-before: right is supposed to do in theory. In practice, it doesn’t work because no browser has implemented it. Instead, I created a blank page element that I manually insert to get those pages in the correct place.
For the h3 and h4 elements, I want to make sure that the following paragraph is connected to those headings. Otherwise, it would be weird if the heading was at the end of a page with its first paragraph on another page.
There’s a lot more to the CSS print specification that browsers haven’t implemented. PrinceXML claims that its main feature is to implement these features and more. I looked into it after finishing the book, but it looks like it might be more involved than I was hoping. It wasn’t clear how to get it working after downloading the zip for me.
But after that, I had a process to get a real ready-to-print PDF of my book. Next, is to make it real.
Publishing
I did a lot of research into self-publishing and ultimately went with Ingram Spark. Most of the complaints were around customer service being slow, but the benefits of worldwide distribution and not being locked into a single Amazonian ecosystem was very enticing.
Before this I bought ISBN numbers from Bowker because then you are able to have more flexibility than if a publisher gives you a free one.
I’ll say that the process was mostly painless. There’s some tools at Ingram Spark that help you prepare your book. The cover template is a little tricky. For my hardcover it wasn’t clear how the template would be used. After getting the first book printed it was more clear that some of the lines were meant to indicate how the cover folds around the book.
We originally made the cover in Adobe Illustrator but then cancelled our subscription because the cost was getting out of hand. Luckily Affinity is free and works just as well. There was a bit of a learning curve but we got the results we needed for the second round of printing. It was close enough such that when I submitted the cover design a third time with a small tweak, I was confident enough to enable the book to be sold without buying myself another copy.
When you’re adding your book to your account, Ingram Spark asks you some questions about the purchase price. In this there’s areas where you need to set the wholesale discount. This is where I got tripped up. Basically, if someone buys your book direct from Ingram Spark, your cut is much higher than if they were to buy it from a middleman like Amazon. This means that it’s better for people to buy it direct from “you” (Ingram Spark). What they don’t tell you is that when Ingram Spark says they have the best distribution network, they mean to resellers, not themselves. I didn’t know this, so when I released my book, I found out it was only available to the US and UK directly through Ingram Spark.
Future
I’ve already started the process of getting the e-book available. It’s in review inside Ingram Spark and I’m planning to do a joint release making the e-book available at the same time that I enable worldwide distribution of the hardcover. I don’t know how long it’ll take for that to reach resellers but keep an eye out on my socials because I’ll be checking periodically and eventually updating the website with links that I get to the book.