Editing ePub files

[Steve]

Storyist for Mac generates ePub files that are compatible with a wide range of readers. If want to create ebook editions of your work and don't want to have to deal with the differences between the platforms, Storyist makes the process quick and easy.

 

However, if you want to customize the layout or design, or need to add proprietary extensions for a particular reader, it is possible to edit the Storyist-generated ePub files. The information below shows how.

 

Note: If you choose to do so, you should be comfortable editing HTML and CSS files, know how to run the epubcheck tool, and be prepared to proofread your content on the readers you're targeting.

 

Contents of an ePub file

 

An ePub file is a zipped collection of HTML, CSS, and XML files. You can use your favorite unzip utility to decompress the files, and then use your favorite HTML and CSS editor to edit the content. Or, you can use an ePub editor like Sigil to open and edit the files.

 

Inside an ePub file, you'll find:

• HTML. There are several flavors of HTML (HTML 4, HTML 5, XHTML). Storyist generates XHTML 1.1, which is widely supported by readers. If you're targeting iPad/iBooks, you could also use HTML5. However, HTML5 is not widely supported by other readers at the moment.
  
• CSS. Storyist generates very simple CSS files for compatibility reasons. Most readers support only a small subset of the spec. The iPad is the exception; it supports most of CSS 3.
  
• mimetype. This is a plain text file that contains the ePub MIME type: application/epub+zip. You shouldn't need to edit this file.
  
• META-INF/container.xml. The container.xml file in the META-INF folder contains a reference to the OPF file in the format specified by the ePub spec. You shouldn't need to edit this file.
  
• OPF. The OPF (Open Packaging Format) file lists the contents of the zip package and describes the order the content is presented. It also contains the book's metadata (card catalog information). If you add files to your ebook, you'll need to edit this file. Please be sure you understand the format before editing this file as it is easy to invalidate your ebook by incorrectly editing this file. It is probably easier to add new files in Storyist and regenerate the ePub.
  
• NCX. The NCX file (toc.ncx) contains the table of contents for your ebook. If you need to edit the order or content of the TOC, this is the place to do it.
  

Changing the paragraph style

 

The most common reason to edit the ePub file is to customize the paragraph style.To override the paragraph style:

1. Locate the CSS for the "p" selector in the OPS/css/main.css file.
   
2. Edit the indentation, alignment, and margin settings to be your desired values.
   

 

The first-line indentation is controlled by the "text-indent" CSS property. The alignment is controlled by the "text-align" CSS property. Note that some readers allow the user to override the paragraph alignment. You can Google these properties for allowable values.

 

Spacing is controlled by the "margin" CSS setting (and the related "margin-top" and "margin-bottom" settings). You should specify these values in "em" units where possible, since you don't know what font size the (human) reader will choose.

 

Adding drop caps to the start of a paragraph

 

Another popular modification is to add drop caps to the first letter in a chapter. There are several ways to achieve this. If you're targeting iPad, the simplest way is to use the first-letter pseudo-class CSS selector as follows:

 

h1 > p:first-of-type::first-letter {
 font-size: 5em;
 float:left;
 line-hight: 0.5;
}

 

Editing the TOC

 

To edit the Table of Contents, you'll need to edit the NCX file (usually named "toc.ncx"). Each table of contents entry is contained in a "navPoint" tag. You can edit the TOC text by editing the "text" tag the "navLabel" tag.

 

		<navPoint class="chapter" id="idD70B037430694CAFACBC923709728E15" playOrder="2">
		<navLabel>
			<text>Title Page</text>
		</navLabel>
		<content src="main-1.xhtml"></content>
	</navPoint>

 

If you want to rearrange items in the TOC, you'll need to move the tags to a new location in the "navMap" structure. Note that "navPoint" entries can contain other "navPoint" entries, so make sure you edit the open/close tags correctly. Also,you'll need to edit the "playOrder" attribute or your ebook will no longer pass epubcheck.

 

Creating Custom Kindle Editions

 

If you're creating a Kindle edition instead of an ePub edition, the steps are very similar. You'll need to:

 

1) Check the "Save intermediate HTML files in a folder with my Kindle file" checkbox in Step 3 of the export process. Kindle files are NOT zip files, and this step will create a folder with the files you can edit.

 

2) Make sure you're familiar with the Kindle Publishing Guidelines and the Supported HTML and CSS for the Amazon Kindle. HTML and CSS support in the Kindle 1 and 2 are quite limited and quirky.

 

3) When you're ready to create a new Kindle edition, run the kindlegen tool from the command line as follows:

 

kindlegen toc.opf -o

[mosscow]

Hi Steve,

 

Thanks for taking the time to map out this helpful tutorial!

 

I've modified the NCX file and changed the Play Orders accordingly.

 

I saved the document, and now - onto the Kindlegen ...

 

This is where I become a N00B. As for "running the Kindlegen" in Mac, do you mean opening the Terminal and typing that command code?

 

I opened that file, and came up with this window:

 

https://skitch.com/mosscow/8jpey/kindlegen

 

Now, am I supposed to hit return and type in the path to the .mobi file I would want to create?

 

Based on the "path to kindlegen" you see in that picture, what exactly would I type if the name of .mobi file would ultimately be "Grave Digger" for instance?

 

Thanks

[Steve]

Hi Mosscow,

 

Yes, you'll want to open Terminal and run the kindlegen tool. Your command line include the following 2 commands:

 

cd <path to toc.opf>
~/Documents/E-Pub\ Tools\KindleGen\kindlegen toc.opf -o <output name.mobi>

 

-Steve