Importing a Book from Scrivener to Mark Book Builder

The new feature in version 0.4 of Mark Book Builder is the ability to import Markdown books. The most common reason to import a book is to import a book from Scrivener, a popular writing app. In this article you’ll learn how to import Scrivener books into Mark Book Builder.

Step 1: Compile to MultiMarkdown in Scrivener

Open your book in Scrivener. Choose File > Compile to open the compiling window.


Choose MultiMarkdown from the Compile menu at the top of the window. Click the Compile button to start compiling. A Save panel will open for you to choose the location to save the book. Click the Export button to finish creating a MultiMarkdown version of the book.

Step 2: Open the MultiMarkdown Book in a Text Editor

In the Finder navigate to where you saved the compiled book and open it in a text editor. If your Scrivener book contains images, the compiled book will be inside a folder with the same name as your Scrivener project. The image files will also be in that folder.

Do not open the book in a word processor like Pages or TextEdit. If you do not have a text editor installed on your Mac, the following free text editors will work:

When you open the book in the text editor, make sure the first line of the text file is not the start of the first chapter in your book. The following text shows an example of the first chapter in your book:

# First Chapter Title #

Mark Book Builder imports Markdown books by creating a Title Page chapter that contains all the text before the first chapter. If the first chapter is the start of the text file, the Title Page chapter will contain the first chapter, Chapter 1 will contain the second chapter, Chapter 2 will contain the third chapter, and so on. Your chapters will be off by one.

If the start of the text file contains the first chapter of your book, add a blank line at the start by pressing the Return key. By adding the blank line, the Title Page chapter will be blank, and the rest of the chapters will import correctly.

Step 3: Import the Book in Mark Book Builder

Now you’re ready to import the MultiMarkdown book in Mark Book Builder. Choose File > Import. Select the MultiMarkdown book from the Open panel and click the Import button.

Mark Book Builder creates a Title Page chapter that contains any front matter, such as the book title and author. Choose Book > Edit Title and Author to set the book’s title and author. The app also creates a chapter for each chapter in the book. The titles are titled Chapter X, where X is the chapter number.

One thing to check is for the following text at the end of each chapter.


Those four dashes indicate that a line should be drawn as a separator for chapters. The four dashes are part of the MultiMarkdown syntax, but Mark Book Builder can’t work with them. You will see error messages in a published EPUB book if you keep them in the text file. Remove the four dashes from each chapter


Mark Book Builder’s importer works best with novels and similar books that are mostly paragraph text. I have noticed the following problems with the MultiMarkdown books Scrivener compiles:

  • Section headings are not imported so they appear as paragraphs.
  • Unordered lists have bullets instead of asterisks so you have to remove the bullets and either add asterisks at the start of each list item or select the entire list and choose Tags > Unordered List.

One limitation in the current version of Mark Book Builder is the image tags in the chapters will not appear in the book. An image tag looks similar to the following text:


You will have to manually create image tags by choosing Tags > Image. Don’t forget to remove the tag that was imported. Keeping the imported tags initially makes it easier to know the file name and where to place the image tag in the text. Automatically creating the image tags is something I want to add before releasing version 1.0 of Mark Book Builder.

Mark Book Builder 0.3

I released version 0.3 of Mark Book Builder. You can download it from this site’s homepage.

The new feature in version 0.3 is basic support for images. To add an image in a chapter, click in the text view where you want the image to appear. Choose Tags > Image. An Open panel appears. Select the image file you want to add. Click the Open button. An image will look like similar to the following the text:


If you want to insert some alternate text, enter it inside the square brackets. The ../Images before the name of the image file ensures the image file appears properly in the EPUB book.

Currently the image support is basic. You can add images to books. If you need to remove an image, you must both remove the image tag from the text view and remove the image file from inside the book. To remove the image file from the book.

  1. Select the book in the Finder.
  2. Control-click, hold down the Control key and click the mouse or trackpad.
  3. Choose Show Package Contents from the menu that opens.
  4. Double-click the Images folder.
  5. Select the image file you want to remove.
  6. Move the image file to the Trash.

The Images folder contains references to the actual files on your Mac. Moving one of the files in the Images folder to the Trash will not delete the actual image file.

Mark Book Builder 0.2

I released version 0.2 of Mark Book Builder. You can download it from the Mark Book Builder page on this site.

The big addition in version 0.2 is the ability to add a cover image to your book. Choose Book > Edit Title and Author to open the sheet. I need to find a better menu title.


Click the Choose Cover File button to choose the cover image file. Click the Update Info button to set the book cover to your image.

With version 0.2 you should be able to publish EPUB books for novels and nonfiction books that don’t have images, footnotes, or tables.

An Introduction to EPUB

When I was writing code to add EPUB publishing to Mark Book Builder, I found there wasn’t a lot of information online about the EPUB file format. In this article I’m sharing what I learned in the hope that it helps others.


Two tools helped me learn about the EPUB file format. Sigil is an EPUB book editor. Being able to open EPUB books and see their contents taught me a lot about the EPUB file format.

IDPF, the group that creates the EPUB specification, has a validator tool. Click the Choose File button to upload an EPUB book. Click the Validate button to see if your EPUB book has valid EPUB.

EPUB Overview

An EPUB book is basically a zip archive of a website. Each chapter of your book is a web page. Like a website an EPUB book can include CSS files to style the book, fonts, image files, audio files, and video files.

The Root of the Archive

The root of an EPUB archive has three items.

  • mimetype
  • META-INF folder
  • OEBPS folder

The mimetype File

The mimetype file identifies the book as being an EPUB book. It is a very short file.


Make sure you don’t press the Return key to create a new line.

The mimetype file must be the first item in the EPUB archive. The file must be uncompressed.


The META-INF folder must have at least one file in it: the container file. The container file has the filename container.xml. The container file specifies where the book’s content (the OPF file) resides in the book’s EPUB archive. The following code shows a standard container file:

<?xml version="1.0" encoding="UTF-8"?>
    <container version="1.0"            
            <rootfile full-path="OEBPS/content.opf"
                media-type="application/oebps-package+xml" />

If you place the OPF file inside the OEBPS folder, you should be able to copy and paste the code into your own container file.

OEBPS Folder

Most of your book’s content resides in the OEBPS folder. Your book’s chapters reside in the OEBPS folder along with any additional files, such as image, audio, and video files.

In addition to text, image, audio, and video files, the OEBPS folder contains the following items:

  • OPF file
  • NAV file
  • NCX file

OPF File

The OPF file, named content.opf, is an XML file that lists the content in the book. The start of the file specifies the XML version and the package version, which is the EPUB version. The following XML code shows the start of an OPF file:

<?xml version="1.0" encoding="utf-8"?>
<package version="3.0" unique-identifier="pub-identifier" 

The version="3.0" part specifies that the book is an EPUB 3 book.

There are three sections you must include in the OPF file.

  • Metadata
  • Manifest
  • Spine


The metadata section contains information about the book. The metadata starts with a <metadata> tag.

<metadata xmlns:dc="">

An EPUB 3 book requires the following metadata entries:

  • Title
  • Language
  • Identifier
  • Modified Date

The title entry specifies the title of the book.

<dc:title id="pub-title">Simple Book: A Beginning</dc:title>

The language specifies the language used to write the book. The following code shows an entry for a book written in United States English:


The identifier is a unique identifier for the book, such as an ISBN number.

<dc:identifier id="pub-identifier">urn:uid:1250064712</dc:identifier>

The modified date specifies the date and time the book was last modified.

<meta property="dcterms:modified">2019-05-22T12:00:00Z</meta>

You must use the format string CCYY-MM-DDThh:mm:ssZ to format the date and time. As you can see in the code example, you need the letter T between the date and time and the letter Z after the time. The EPUB standard is very picky about the modified date. You can’t just enter the date. You have to include the date and time in the right format.

Common optional metadata entries include the book’s author, publisher, and copyright. The following code shows an example of a metadata entry for a book’s author:

<dc:creator>Mark Szymczyk</dc:creator>

Add the closing tag to end the metadata section.



The manifest contains a list of every file in the EPUB book. The following code contains a short example of a manifest:

    <item id="nav" href="Text/nav.xhtml" media-type="application/xhtml+xml" 
    <item id="Chapter1" href="Text/Chapter1.xhtml" media-type="application/xhtml+xml"/>
    <item id="Chapter2" href="Text/Chapter2.xhtml" media-type="application/xhtml+xml"/>
    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>

There are four items in the example: the NAV file, two chapters, and the NCX file. Each manifest item has the following properties:

  • id, which identifies the manifest item.
  • href, which specifies where the item resides in the OEBPS folder.
  • media-type, which specifies the type of file. Text files usually have the type "application/xhtml+xml".

The NAV file has an additional property that specifies it is used to navigate the book as a table of contents.

A real book is going to have a much longer manifest. There will be a manifest entry for each chapter in the book as well as an entry for each image used in the book.


The spine contains a list of all the files in the book in linear reading order.

<spine toc="ncx">
    <itemref idref="Chapter1"/>
    <itemref idref="Chapter2"/>

There is an <itemref> tag for each file in the spine.

Navigation is an important feature in an ebook. People want to jump to specific chapters and sections in a book. As a reader it would be annoying to have to navigate page by page.

EPUB has two files for book navigation in e-readers: the NAV file and the NCX file.

In EPUB 3 you use the NAV file, named nav.xhtml, to declare the book’s table of contents. The start of the file contains boilerplate code identifying the book as an XHTML document.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html>

<html xmlns="" xmlns:epub="" 
    xml:lang="en" lang="en">

The header follows. It usually contains the title of the book.

<title>Simple Book: A Beginning</title>

The table of contents is an ordered HTML list. Each list item is an HTML link whose destination is the location of the item inside the EPUB archive.

<nav epub:type="toc" id="toc">
<h1>Table of Contents</h1>
    <li><a href="../Text/Chapter1.xhtml">Chapter 1</a></li>
    <li><a href="../Text/Chapter2.xhtml">Chapter 2</a></li>


NCX File

The NCX file, named toc.ncx, also contains the book’s table of contents. The NCX file provides compatibility with older EPUB versions.

The start of the file contains boilerplate code identifying the book as an NCX document.

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
<ncx version="2005-1" xmlns="">

The header follows.

    <meta content="urn:uid:1250064712" name="dtb:uid"/>
    <meta content="0" name="dtb:depth"/>
    <meta content="0" name="dtb:totalPageCount"/>
    <meta content="0" name="dtb:maxPageNumber"/>

The first meta entry is the identifier. The identifier must match the identifier you gave the book in the metadata in the OPF file. The second meta entry lets you specify how many levels and sub-levels appear in the table of contents menu. You shouldn’t have to change the last two meta entries.

The title of the book follows the header.

    <text>Simple Book: A Beginning</text>

The table of contents appear as a navigation map. Each item in the navigation map has a navigation point. The navigation point contains an ID and its order in the book. Each navigation point includes a navigation label and the location of the item in the book.

    <navPoint id="nav_1" playOrder="1">
            <text>Chapter 1</text>
        <content src="Text/Chapter1.xhtml"/>

    <navPoint id="nav_2" playOrder="2">
            <text>Chapter 2</text>
        <content src="Text/Chapter2.xhtml"/>

Text Folder

Most EPUB books place their chapters inside a Text folder inside the OEBPS folder. It’s not mandatory to have a Text folder, but having your chapters in a separate folder keeps your EPUB archive organized.

Additional Folders

In addition to a Text folder, having the following additional folders can help you keep track of your book’s files:

  • A Styles folder for CSS files to style your book
  • An Images folder for your book’s images
  • A Fonts folder for fonts you embed in your book
  • An Audio folder for audio files
  • A Video folder for video files

A Sample Chapter

The last thing your EPUB needs is chapters. Chapters are XHTML files. You should have one XHTML file for each chapter in the book. The following markup shows the shell of an XHTML file for a chapter:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html>

<html xmlns="" xmlns:epub="" 
    <title>Chapter Title</title>    



The contents of the chapter go between the <body> and </body> tags.

Additional Reading

Elizabeth Castro’s book, EPUB Straight to the Point, has a chapter on the EPUB file format that I found helpful.

Liza Daly wrote two articles on IBM’s developer site on EPUB that may help you learn about the EPUB file format.

If you prefer video, Apple has two WWDC videos on EPUB.

AD Book Builder 0.2

I released version 0.2 of AD Book Builder. You can download it from the AD Book Builder page on this site.

Version 0.2 provides EPUB support. You can publish EPUB books with simple formatting needs, such as novels.

One user interface change in version 0.2 is the addition of a Book menu to the menu bar. The Book menu has two items: a Publish item to publish a book, and an Edit Title/Author item. The Edit Title/Author menu item opens a sheet to enter your book’s title, author, and unique identifier. If you have an ISBN number, use that as the book’s unique identifier.