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:

%% 01 Short description
# The Heading

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.

If you export from Ulysses using one of the included templates, there’s a blank page at the front. In iBooks this means the start of the book in on the right page in a two page layout. With a custom stylesheet, the books starts on the left but the blank section is still there. Looking at the table of contents you’ll see a blank line at the top. This is a link to the empty section.

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 solution

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:

$ tree
.
├── META-INF
│   └── container.xml
├── OPS
│   ├── book.opf
│   ├── cover.html
│   ├── css
│   │   └── style.css
│   ├── index.html
│   ├── navigation.html
│   └── toc.ncx
└── mimetype

The files that need editing are:

• index.html
• toc.ncx
• navigation.html

For index.html delete the highlighted portion.

For toc.ncx delete the highlighted portion.

For navigation.html delete the highlighted portion.

Those are the artifacts caused by the comment at the top of the sheet. Once they’re gone the ePub file will behave. It will also now covert to a Kindle .mobi file.

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:

• In the Finder, select the three top level items: META-INF, OPS, and mimetype.
• Right-click and choose “Compress 3 items”
• Change the name Archive.zip to My Great Ebook.epub¹.

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.

---

1. Or your real title. Either way I won’t judge. ↩