J. Zachary Pike's

Blog of the Strange and Fantastic

Fiction, Gaming & Writing

Indie Publishing

Use An HTML Compiler to Publish Ebooks Faster

HTML, Word documents, and most other ways that indie authors have to format their ebooks all have the same common flaw: rework. If you sell multiple books on multiple platforms, you can quickly find yourself buried in files. That’s because if you want to follow best practices, your back matter should have platform-specific links. For example, if you buy Orconomics on Amazon, all of the links in the back of the book should take you to Amazon books. Retailers and readers alike prefer this approach. However, if you have three books available on five platforms, you need fifteen separate HTML files. That’s painful. Every time you want to edit your author bio, add a book to the back matter, or update your newsletter invitation, you have to open, update, and save 15 different files.

Case in point, a while ago I wanted to add the new logo for Gnomish Press to the front of all of my ebooks. It’s a simple change, but it can still take 10 minutes to open fifteen different files, paste a line of code in the right spot, and save them out. So instead, I opened one file, made the change once, and automatically updated fifteen different files in just under twenty seconds.

It was easy. It used good, old-fashioned HTML. And it didn’t require expensive software. Want to see how it’s done? Read on.

Why I Use HTML to Format Ebooks

If you’re an independent author, I think HTML is the best way to format and maintain you ebook catalog. It gives you the best control over the formatting, and it ensures that your ebook editor isn’t injecting a bunch of useless or nonsensical code into your books (I’m looking at you, Microsoft Word). Learning it can be a bit of a curve, but there are excellent guides available for free online, and even more detail in books like Guido Henkel’s Zen of Ebook Formatting. Besides, if you can learn all of the convoluted hoops you have to get your Word document through to get it ready for Smashwords or Amazon, you can learn HTML.

But beyond that, there’s a new reason to use HTML for ebook formatting: you can compile HTML files using a compiler and the Kit language.

Working in Pieces With An HTML Compiler

You may be wondering what a compiler is. In simplest terms, it’s a program that compiles code.

There’s a computer science definition for compiling, but for creating ebooks, the more common definition of “compile” is more useful. To compile means to produce something by collecting information from other sources. I’ve been using an HTML compiler to do exactly that: it compiles an HTML file from many source files. None of the source files are altered or deleted during the process of compiling, but they all affect the final compiled file.

Dividing one file into many pieces doesn’t save much time in and of itself. However, once you have many files that use the same pieces, you’re gaining efficiencies. All of my ebooks compile using the same author biography. Because all of those books use the same file for my biography when I compile my ebooks, I can change my biography in all of those books by changing that one piece.

There are a number of HTML compilers you can use. If you’re on a Mac, I recommend you use CodeKit. (It’s what I use). If you’re on a PC or Linux, I’ve read that Prepos is a good substitution. Either one has a free trial and a price tag beneath $35. If you’re more code-savvy than I and comfortable using a console, you can even compile them using node.js, which is free. Any compiler will work, provided it can compile the open-source Kit language.

The Kit Language

The Kit language was developed by the makers of Codekit to help developers compile HTML. Kit extends HTML; .kit files look like HTML snippets. They don’t display in any browser; they’re intended to be compiled into final HTM files.

But beyond HTML, the Kit language has two features that make all the difference: include statements (or import statements), and variables.

Include Statements

Include (or import) statements allow you to bring one kit file into another when compiling. For example, if you wanted to include your author biography at the end of your books, you could write it (as HTML) in a file called _bio.kit. Then I’d include the following line of code at the end of each of my books’ .kit files:

<!-- @include _bio.kit -->

That line pulls in the biography in wherever the include statement is. It’s just a straight replace—in the final HTML file, the include statement will be gone and replaced by whatever HTML is in _bio.kit.

Include statements let you pull your files together, which is critical for sharing common elements. But pulling together a bunch of static files will only take you so far; variables are what give you scale.


A variable, as in algebra, is a symbol that stands in for something else. Variables are an essential part of programming, so if you’ve any familiarity with coding you’re probably knowledgeable about what a variable is. If you’re not, don’t worry. This is pretty straightforward.

All a variable does in the kit language is let the compiler know that when it sees a particular variable name, it should swap it out with a different bit of text. Of course, you have to declare what that variable should be swapped with before you use it. Once you do, you can insert the variable anywhere to use it as text.

For example, say I had the following two lines in my .kit file.

<!-- $Message = Variables are great!-->
<p>My message to you is that <!-- $Message --></p>

The words with $ in front of them are variables; you don’t have to name your variables this way, but it’s a common convention. The = sign tells the compiler to assign the value on the right to the variable on the left.

When the HTML compiler processes this .kit file, it will swap the variable $Message with it’s assigned value. When it processes the second line of code, it will write the following line of code in the output HTML file:

<p>My message to you is that Variables are great!</p>

It’s a simple example, but imagine setting the title of a book in a title page, or controlling the links in your back matter using variables. Variables let you reconfigure how files behave in different files, effectively transforming some files into templates rather than content. (Or both!)

Putting It All Together

Once you’ve determined what you want to control with include statements and variables, it’s just a matter of configuring your .kit files to pull in the right data. For example, I might create a .kit file called _authorPage.kit, with a line like:

<p>Visit my <a href="<!-- $authorPageLink -->">Awesome Author Page!</p>

Then in each of my book’s kit files, at the start of the file, I’d set the $authorPageLink variable to a page that I think would be appropriate for readers on the corresponding platform. For example, in a book on Amazon, I’d set the link to:

<!-- $authorPageLink = http://www.amazon.com/author/jzacharypike -->

And then near the end of each book, I’d include the file that uses the variable, like so.

<!-- @include _authorPage.kit -->

When I compile each of the books, all of them will include the line “Visit my Awesome Author Page!” And each will link to the author page that’s best for that reader. But when I come around to the fact that this is a pretty weak pitch for my author page, I can edit one file and update all of my books at once.

Once you start using the Kit language to compile your HTML ebooks, you can start to see all of the possibilities for making your back catalog easier to work with and scale. You can do things like:

  • Share your author bio, newsletter pitch, and other marketing across all of your books.
  • Use variables to change the links in your back matter, so your book files for Amazon always have Amazon links in the back.
  • Save time and format consistently by making a title page template, and then use variables to populate it.
  • Tailor content to particular retailers
  • And much more.

There aren’t many limits to what you can do with this approach. And it can result in significant efficiencies over time, provided you have enough books. Spending some time to set up your library in .kit files can pay off big dividends over the course of your indie publishing career.

Honestly, the most time-consuming part was developing my system for file structure and naming conventions. And I can help you with that.

The Ebook Machine

It took me a while to set up my .kit files and variables for formatting my ebooks, but now that I’ve got it just the way I like it, I’m making it available to the independent publishing community. I’ve created template files, and a (rather silly) set of examples that you can download now at www.jzacharypike.com/ebookmachine/  They’re under a creative commons license so that you can use them forever at no cost. And if you’d like more guidance using the files, I’ve written a short guide that gets really in depth on how I’ve set up the files and the best way to get your book library set up.

You can see it in action here:



If you format your ebooks in HTML, using kit files can save you lodes of time in the long run. I’ve been formatting my books this way for half a year, and I’m already reaping the rewards in time saved. I highly recommend you try it out, even if you just play with my sample files for a while to see if it’s right for you. (And either way, please let me know how it goes in the comments.) It’s a better way to work.


Leave a Reply

Featured Book

Say "Hello"


Copyright © 2014, Gnomish Press LLC. All rights reserved.
Disclaimer | Terms & Conditions | Privacy Policy
Looking for my UX and design portfolio? It's moved.