Hyperlink with Ampersand Causes InDesign Export to EPUB to Fail

I've been working on a book about creating EPUB files using InDesign and other tools for about six months. Today I sent the final files to the printer—it should be in bookstores by the end of the month. Then I chose Export to EPUB and it failed. Just failed. No details, no clues. It did give me this lovely dialog box:

I had been converting RGB images to CMYK, so I thought maybe that was the culprit. I changed them all back. Nothing. Not only nothing, but each time I tried an export, the script would stay on the screen, requiring me to quit all the way out of InDesign.

I thought maybe a large PDF file at the end of the book was the trouble, but that didn't make sense since it had exported fine with it just two days ago. Thanks to suggestions from my Twitter friends, I restarted and repaired permissions.

I googled "InDesign EPUB Export Failed" but only got a few people with the same problem and no solutions.

I emailed a couple of InDesign gurus I know, including Teus de Jong, who has written a number of useful scripts for InDesign, including one that adds the otherwise missing required date and fixes the annoying bug that breaks hyperlinks and cross-references in exported EPUB files.

Teus wrote me back offering to look at my files with a debugger (since the dialog box was so vague), but it's 200Mb and seemed a lot to ask. So instead I asked if I could run the debugger myself.

No problem, he said. Open the OEBExportMenuItemLoader.jsx file, which is in the startup scripts folder, within the HTML for Digital Editions (or XHTML for Digital Editions) folder, inside your main InDesign program folder. (I just opened it with BBEdit.)

On line 31, he said, change var DEBUG = false; to var DEBUG = true;

Next time you try to export the EPUB, a DigitalEditionsExportLog.txt file will appear (on his PC it goes to My Documents, on my Mac it appeared in the Documents folder).

So, I followed his instructions, reexported the file, and lo and behold the DigitalEditionsExportLog.txt file appeared as promised. There was lots and lots of stuff about creating this style and that style, but at the very end, it said:

Error: XML error in line 474
- Not well-formed (invalid token)
Error Number: 60
File: undefined
Line: 794

Line 474? XML error? I puttered around InDesign's help files trying to see how to look at the XML representation of my file. Where would that be? I wrote Teus one more time hoping I wasn't bugging him too much and he told me that that probably referred to a temporary XHTML file created by the script.

I went back to the DigitalEditionsExportLog.txt and the last XHTML file referenced before the error was this:

Entry: OEBExporter.addChunk
temp file should be: /private/var/folders/xf/xfcWz+ZZGZKuQUR7NebUiU+++TI/TemporaryItems/onedoc_4/OEBPS/ePub-STTP-5.xhtml

I opened Terminal and copied in the whole path to the file, without the file name, followed by a return. (There must be an easier way to get to this location, but I confess I don't know what it is.)

Then I typed open ePub-STTP-5.xhtml.

The temporary ePub-STTP-5.xhtml file opened in BBEdit.

I scrolled down to line 474 and found this:

<div class="numbered-steps" xml:lang="en-us">
2 Download both KindleGen and the Kindle Previewer from <span class="link"><a href="http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621">Amazon’s site</a></span>.</div>

It turns out that the hyperlink that I created to Amazon's site contains an ampersand, and when InDesign tried to convert it to XML within the hyperlink, it didn't properly code the ampersand, and the resulting XML was badly-formed (a grand faux-pas in XML land). InDesign didn't know how to recover, and so stopped exporting the file. (If you're not sure what's causing the error, you could use a syntax checker to point out the error. In BBEdit, you'll find it at Markup > Check > Document Syntax)

I went back to my InDesign file, removed the hyperlink (I just put the URL in the text instead), and exported again, and it worked like a charm. I'll put the link in the EPUB by hand (properly coded!)

Moral of the story: Don't add hyperlinks with URLs that contain ampersands to an InDesign document if you intend to export the file to EPUB.

And second, if InDesign fails to export to EPUB, you have a number of tools at your disposal.

And thank you, thank you, Teus de Jong!