This is what seems to be the second in a series about making ePub format eBooks with Ulysess III. Yesterday, I compared a few options for making eBooks. I found the least troublesome way was to just simply export from Ulysses using a custom stylesheet. Today’s post is about how to fix an annoying export bug.

Ulysses is a three-paned editor. The second pane is a list of sheets in the current working folder. The first part of the first line of any sheet is shown there. The sheet can be sorted by name, using this first line. But what if the sheets in a longer project don’t have titles that are alphabetical?

This is where a note can keep things organized. A quick note at the top of a sheet with a leading number keeps everything in order. There’s an option to sort by a custom order, but it applies to all folders. This is why I override it for certain projects.

A lot of my sheets start with something like this:

This one is going to sort to the top, just where I want it. But there’s one slight problem. It breaks things.

A comment—in either block (%%) or inline (++) style—at the top of a sheet gets translated to an empty paragraph. This isn’t a problem with HTML. It’s just a extra carriage return at the top of the file.

With ePub export it’s much more of a problem. There’s going to be a blank line in at the top of the contents. And depending on the stylesheet used, maybe even a blank starting page. What’s happening is that the empty paragraph is being converted into an empty section. Which in ePub formatting is an empty chapter.

The following are examples from iBooks. I made up a quick sample using the excellent Lorem Gibson text generator.

This only a cosmetic annoyance when reading the book in iBooks. The problem comes when using the KindleGen file converter to make .mobi files. It chokes on the blank section and won’t do the conversion.

The easy way it to delete any comments that come before the first heading. This is the best way to go in most cases. But if you really need to keep sheets in order, it’s not so great.

If you keep comments in, and export to ePub, there’s only one way to fix it. You have to open the ePub file and edit the contents. Ebook surgery isn’t hard, and I’ll walk you though it.

First we need to unpack the file. ePub is just a zip archive with an .epub extension instead of .zip. There’s a couple of ways to do this. The command line unzip command works, along with the free The Unarchiver app.

Start by creating a new folder, and move your ePub file into it. Then, right click and Open with > Other… and choose The Unarchiver. From the command line do unzip <filename>. Now you’ll have a folder with the following contents:

The files that need editing are:

For index.html delete the highlighted portion.

But wait, how does a folder of files get turned back into an ePub?

I’m glad you asked!

It’s simple. Just zip the files up and change the .zip extension to .epub!

Here’s the easy way:

See, I told you an .ePub file is just a zip file. Now your file should be fixed and work correctly.

As I write this, the makers of Ulysses have a new version that should come out soon. Hopefully this bug will be fixed.