Coding a book
I’ve done a lot of writing in the past few years, all on a Mac, and mostly in Sublime Text. I publish this site using Jekyll + GitHub Pages, so it’s easy for me to write blog posts and whatever with Markdown files. But when it comes to writing books, the options get a little interesting; there’s not much out there that feels as safe as an author might want to feel when writing.
Sure, there are plenty of online editors and other kinds of authoring tools. But I really wanted to use version control so I could more easily track progress over time, and I’m comfortable with my existing editor. I certainly didn’t want to worry about some online tool disappearing in the middle of writing my book draft. I also wanted to be able to collaborate with others.
Given that there’s not a lot written on technical workflows of authoring or publishing a book, I figured it might be nice to detail how I chose to do it in case others are exploring the same questions!
Writing a book without Word
In 2014, when I signed a contract to write Designing for Performance with O’Reilly, I learned all about their editing and formatting tools for authors as they draft and collect feedback on their work. They’ve got an integrated system where you can use a git repo to upload AsciiDoc files.
When you’ve pushed your changes, you can visit a UI on their author site, and generate a PDF and HTML version of your revised content from your repo. The PDF output uses a typical O’Reilly technical book layout; though it turned out to not be relevant to how my book’s layout turned out, it still helped me get a sense of things. The HTML version connected to a separate system where your feedback crew could read your work and leave comments on paragraphs.
AsciiDoc, for me, was real fun to use. It’s pretty well-documented, but O’Reilly went one step further to write about using it with Atlas, their publishing UI. Handy, eh? This meant that I could go so far as to create my dedication page using [dedication], or even specify that a page contained blurbs from famous people with ["dedication", role="praise"]. AsciiDoc was nifty in that it captured much of the markup that I’d want to have for laying out a book.
When Destiny and I co-authored Building a device lab, we collaborated using Google Docs. It definitely suited our purpose; we were writing a short book and mostly just needed to add comments or questions for each other as we went and could go clean up later. Personally, I find Google Docs’ version changes hard to read, so I’m glad that we didn’t end up needing to use version control for any major reason. For shorter writing projects, Google Docs makes total sense! For larger projects where I want more fine-grained control and to look at things in chunks rather than one long document (or flip between multiple browser tabs), I’m going to stick with my text editor and a git repo.
Exporting a book from code to Word
PANDOC IS EVERYTHING. I use it simply to concatenate files (of pretty much any kind) and export them into a different format. It is the light of my life. The only hurdle I’ve found is that it doesn’t export to Pages; when my editor wants a Pages file, I’ll export to Word, then open it in Pages and save it as a Pages file there. Hilarious.
Publishing a book in HTML (and Markdown)
The publisher was on board with me making the book available on my website under a Creative Commons license, but by the time this happened, there was no original source code for the book. My words had gone through a proofreading/copyediting round in a Word doc, then hand-laid out using InDesign by the publishing team. What I did have was the PDF output, so I went to work exporting it.
This meant, unfortunately, a lot of copying and pasting and triple-checking to make sure I’d captured everything. Because the PDF had a custom layout, a lot of strange spacing and ordering issues happened when I exported from it. Sometimes things didn’t paste bolded or italicized. It definitely took a few days of work to get a cleaned-up version into Markdown.
I created a Jekyll instance and got it up and running with GitHub Pages. I split the chapters into different Markdown files and eventually got things mostly cleaned up. There were a few places where Markdown just couldn’t work; though it can handle some gentle HTML tags, I needed to do some fancy things like add footnotes within code blocks, which I’d get to later.
Because all the content was there (just not styled), the last step before formatting was to add anchor tags for each header. It was important to me so that I could reference stuff easily later in a tweet. But there are a lot of chapter subheaders. And because it’s a book about web performance, I didn’t want to load a script on pageload to dynamically insert all those anchor tags.
So, I loaded a script once to dynamically insert all the anchor tags for headers on every page, then I viewed source and grabbed the exported HTML from the Jekyll build locally. Hacky, right? But it worked great. And then I was able to eliminate the script!
I started designing the site and finished adding markup to set the foundation for any custom formatting that was left. The preface, forewords, etc. still live in Markdown, but the rest of the chapters included more custom HTML, so they exist as HTML files because Markdown wasn’t having it. Still, Jekyll allowed me to make a fast, static site while still easily implementing repurposable headers/footers etc. and more custom markup per chapter.
I learned a bunch of stuff by doing this work. I spent a ton of time testing the responsiveness of the site, both in terms of screen size and web performance. Because I wanted the book to look like a well-laid-out print book, I spent a lot of time choosing fonts and subsetting them. I also spent a ton of time optimizing the subtle hummingbird image in the header, finding the right image file format and export settings. Same for the favicon. Optimizing favicons is one of those rabbit holes I look forward to avoiding again in the future.
Oh, and I added Google Analytics events to track clicks on the banner to buy the book, links to the note about where proceeds are donated, and a few things on the index/table of contents. It was a nice throwback to years ago when I used the old-school GA events code for 404’s and wrote a Smashing Mag article about it.
The book’s site lives at http://designingforperformance.com/. It was a fairly manual process to code the book, but I still loved it. There’s something really fun about marking up a book. I’d do it again in a heartbeat.