EPUB Generator

Overview

Steelkilt automatically generates your EPUB content as you work.

For the purposes of EPUB Generation, “work” means any of the following:

  • Structural changes to your Book, such as:
    • Adding or removing Parts, Documents or Chapters
    • Importing text (which results in new Chapters)
    • Reordering Parts, Documents or Chapters
    • Moving Documents or Chapters in or out of Parts
    • Converting a Document into a Chapter and vice versa
    • Importing Resources
  • Editing text
  • Changing settings associated with Books (metadata)
  • Changing settings associated Parts, Documents or Chapters
  • Renaming Books, Parts, Chapters, Documents or Resources
  • Automatic or manual fixes of EPUB Content Problems

EPUB Generation can also be triggered manually (see below).

EPUB Generation Process

When Steelkilt generates EPUB content, it will:

  • Convert Book settings into EPUB metadata
  • Create a Resource for the Book title page
  • Create Resources for Part title pages
  • Create Resources for Documents and Chapters
  • Use the arrangement of Documents, Chapters and Parts in the Project Navigator to create EPUB manifest, spine and navigation data
  • Convert Markdown in Document and Chapter text into XHTML
  • Convert appropriate symbols in Document and Chapter text into HTML entities
  • Convert Document and Chapter text into XHTML

Resources rely on the following for generation:

  • Templates
  • CSS

Exclusions from EPUB Generation

If you edit any of the following automatically generated Resources, they will be locked:

  • container.xml
  • book.opf
  • nav.xhtml
  • title.xhtml
  • Resources that represent Parts
  • Resources that represent Documents or Chapters

Locked Resources are excluded from EPUB Generation. This behavior allows you to preserve customizations to these Resources.

Warning

When a Resource that represents a Document or Chapter is locked, the corresponding Document or Chapter will also be locked. This behavior prevents you from inadvertently making text edits to Documents or Chapters that cannot be written to a locked Resource.

Similarly, when the book.opf Resource is locked, the corresponding Book’s Settings will be locked. This behavior prevents you from inadvertently changing Book Settings that cannot be written to metadata within the locked book.opf.

But edits to nav.xhtml or book.opf will not lock the Project Navigator, meaning that structural changes to the Book are not prevented. Restructuring the contents of a Book when nav.xhtml or book.opf are locked will, in most cases, result in EPUB Content Problems. To resolve the EPUB Content Problems (and bring book.opf and nav.xhtml back into sync with your Book’s content), take a copy of the locked files, unlock them, and trigger manual EPUB Generation (see below)

Manual EPUB Generation

To regenerate your EPUB, open Code Editor and select Package (or an automatically generated child of Package, such as the XHTML folder, or a Resource representing a Document, Chapter or Part), and do either of the following:

  • Right-click the Resource and choose Regenerate
  • Open the Code Menu and choose Regenerate

Related Topics