Fixed Layout EPUB Assistant In InDesign: ePubCrawler


eCanCrusher, the EPUB zip/unzipper is now available separately from ePubCrawler. Visit for more info.

As of December 27, 2013, ePubCrawler has ceased to be donation-ware. It will remain available as-is (see below), but there won’t be any more updates.

Over the course of 2014, it will be gradually superseded by Rorohiko’s new Crawler product and its FL-EPUB personality. More info on this work-in-progress:

People who donated US$50 or more for ePubCrawler before December, 27, 2013 will be entitled to a free license of the Crawler+FL-EPUB product if and when it becomes available.


Click the link below to download a zip file with the software (currently version 0.2.5. Supports InDesign CS3 and higher).

Please read the documentation further down this page. This is not a point-and-click software!


For info on what changed in ePubCrawler since the last version, please check out the ‘History‘ near the end of this page. Download links to older versions can also be found near the history.

Take your time

We understand you might be rushed and eager to get started, and you might get a fair way without reading any instructions.

However, we strongly recommend that you take some time to read up on ePubCrawler. With great power comes great responsibility!

Before you dive in, make sure to check the ‘Essential Links‘ section with required reading and viewing material.

If you don’t like reading, go to the ePubCrawlerVideos‘ section.

ePubCrawler is very flexible and can be reconfigured to generate a wide range of possible fixed-layout EPUB variants. If you don’t like what it does, you can change things.

This web page changes frequently as we are continuously improving ePubCrawler and the documentation to go with it.

IMPORTANT: you need to be aware of the ePubStyle setting inside the config.ini file, which is located in the ePubCrawler folder. Open config.ini in a text editor for more info – the file is heavily commented.

By changing the ePubStyle setting you can generate wildly different EPUBs, simply by selecting one of a number of pre-configured EPUB styles.

You can also add and use your own EPUB styles (see ‘Customizing ePubCrawler).

Make sure to read up on ePubStyle, and set ePubStyle to something that suits you best – for example use percentages instead of default to select using  CSS ‘%’ measurements vs. ‘px’ measurements.

If you want to try out the (still very incomplete) read-aloud functionality, set ePubStyle to readaloud.

For more advanced control over the generated EPUB, you can tweak the various templates and snippet files.

For installation instructions, go to the ‘Installation‘ section.

Please let us know about any bugs, improvements, ideas, kudos – e-mail us at [email protected]

What is it?

ePubCrawler takes an InDesign document, and converts it to a collection of XHTML and CSS files. There is also eCanCrusher, which comes with ePubCrawler.

You can then drag-drop an EPUB folder onto the eCanCrusher application icon, and it will convert the folder into an .epub file.

The resulting EPUBs are not beautiful, and need some ‘Tender Love and Care’, but they are usable. For best results, further fine tuning is needed, but ePubCrawler does a lot of the necessary work for you.

ePubCrawler is fully CSS/XHTML template driven. You feed an InDesign file + CSS/XHTML templates in one end, and an EPUB comes out at the other end.

The underlying philosophy is: ‘power to the user’.

ePubCrawler is extremely configurable. Maximizing that power can take an investment of time and effort on your part, as building and fine-tuning your own CSS/XHTML templates can get pretty intricate.

Of course, you can use ePubCrawler ‘as-is’, without knowing much about EPUB, and just point and click and use the sample EPUB styles that come with the tool.

The CSS/XHTML templates are user-adjustable, so you can easily tweak the output. And because it’s template-driven, ePubCrawler is not tied into any particular type or version of EPUB standard.

Depending on the type of template you feed into it, different EPUB styles can pop out at the other end. You are encouraged to create your own EPUB styles.

ePubCrawler is work-in-progress: there is still a lot of work to be done, but even in its rudimentary shape, it is quite powerful.

The download link is at the top of this page. Installation instructions can be found in the  ‘Installation‘ section.

How it works.

ePubCrawler will merge two different sources of information and spit out an EPUB folder.

First of all, it will inspect your current InDesign document, and harvest information: the positioning of individual frames, their contents, linked images, all the words and their formatting…

Second, it will use the contents of a folder called ePubCrawlerTemplate which contains configuration information and a skeleton EPUB structure, and a slew of template and template snippet files.

Most of the text files in this skeleton EPUB structure contain a smattering of special placeholders (e.g. $$PAGE_WIDTH$$).

Placeholders are wedged between $$ and $$ or between $($ and $)$.

ePubCrawler will replace all such placeholders with real data, harvested from the InDesign document when it merges the InDesign information with the skeleton EPUB structure from the ePubCrawlerTemplate folder.

The merged result is then stored in a folder next to your InDesign document.

This folder’s name will be based on the name of your InDesign document.

If your InDesign document is called MyDoc.indd then the merged EPUB folder will be called MyDoc.

ePubCrawler will not overwrite any existing folders, so if there is already a folder called MyDoc, it will create a folder MyDoc_1 instead. And if in turn MyDoc_1 already exists, it will instead create MyDoc_2, and so on.

That means that if you run ePubCrawler a few times in a row, you’ll end up with a multitude of EPUB folders next to your document, and the one with the highest number appended to the name will be the latest.

Included with ePubCrawler is a small drag-and-drop utility called eCanCrusher.

Both Mac and Windows versions are provided. See the ‘Installation‘ section for more info on how to install it.

You can drag any of the folders created by ePubCrawler onto the eCanCrusher icon to create an .epub file.

Running ePubCrawler

Once ePubCrawler is installed (see further), you’ll open an InDesign document, and bring up the scripts palette (Window – Utilities – Scripts menu).

Then look for ePubCrawler or ePubCrawler.jsxbin on the Scripts palette and double-click it.

For smaller documents, it’ll only need a split second to do its work.

Switch to the Finder or Explorer, and look for a folder that should have appeared next to your .indd file.

For example, if your document is MyDoc.indd, look for a folder called MyDoc (or MyDoc_1, MyDoc_2…).

This folder contains the EPUB structure, which can be used as-is. But in most cases, you will want to further fine-tune it.

The template.css file will list entries for each paragraph and character style in the document.

These entries will be defined with rudimentary CSS style info. They will work, but for optimal results, you’ll need to adjust their definitions; the default font-family information that is generated will most probably be incorrect.

To help you adjust the definitions, ePubCrawler puts comments into the template.css file, showing the InDesign style definitions.

The most important bit of information in these comment blocks is the fontMatchString – this is the string that will be matched against the optional font mapping information you can define in your config.ini file.

To help ePubCrawler with the conversion, you should also spend some effort preparing your InDesign document.

Convert any images that are not JPEG or PNG into JPEG or PNG, and place the converted files instead.

Then also ‘flatten out’ any complex transformation (e.g. image rotations). ePubCrawler does not currently know how to cope well with complex image transformations. It can currently handle some scaling, shifting, rotating, but not skewing, etc…

Customizing ePubCrawler

The main config.ini file residing inside the OEBPS folder is a text file; you can open it in a text editor.

(Sublime Text 2 on both Mac and Windows, or TextWrangler on Mac, and NotePad++ on Windows are what I tend to use for text editing).

config.ini uses the INI file format which is an easy-to-grasp, text-based, human-readable format.

Various settings can be activated, deactivated or modified by editing the config.ini file and re-saving it.

Future versions will have a more user-friendly approach, but for now, you need to open the config.ini in a text editor.

# **************** MAIN SECTION ************************


# ePubStyle: select one of the available ePub styles (i.e. the name of a folder that
# can be found in the ePubCrawlerTemplate\ePubStyles folder). This is the only setting
# you cannot override from a config.ini inside a specific ePub style folder.

ePubStyle = plainpixels

# What DPI to use for exporting images. 144 dpi makes ePubCrawler export twice as
# many pixels as needed (144/72 = 1), so allows for more zooming
imageExportDPI = 144

# Set generateCompactCode to 1 to reduce the amount of white space in the
# generated code
generateCompactCode = 0

The settings that might be of most interest are listed here; for more info, consult the config.ini file inside the OEBPS folder.


Inside the ePubCrawlerTemplate folder you’ll find a folder ePubStyles. This folder contains a number of subfolders.

Their folder names are plainpercentages, plainpixels, scaledpixels,…

Each of them contains a set snippets of XHTML or CSS to be used for generating a certain ‘style’ of EPUB.

For example, if you wanted to generate CSS that uses % values instead of px values, set ePubStyle to plainpercentages.

The ePubStyle setting inside the config.ini should refer to one of the folders you find inside the ePubStyles folder.

Feel free to add, copy, edit additional folders and prepare your own snippets.

A common approach is to copy one of the existing folders, and then rename the copy; e.g. copy plainpixels to myplainpixels.

Simply by doing that you’ve made available a new ePubStyle called myplainpixels.

Then you would add to and edit the contents of myplainpixels as desired.

If you want to change some of the standard behavior that’s driven by files that reside in OEBPS, you’ll also want to copy config.ini and some the templates from OEBPS to your customized myplainpixels folder, and then modify them to suit.

The idea is that the files in the OEBPS folder define your ‘baseline’ behavior, and the files inside the selected ePubStyle subfolder can then modify or override this baseline behavior, as needed.

For example, you could create an empty folder called baseline inside ePubStyles. That would automatically make a new ePubStyle called baseline available, and it would be driven only by the contents of the OEBPS folder, without overriding any of the baseline behavior.


When using one of the styles plainpixels or plainpercentages, any images encountered in the InDesign file are cropped and re-exported to a certain pre-set resolution.

The scaledpixels EPUB style instead attempts to use unmodified copies of the original image files. If you’d select scaledpixels as your EPUB style, manipulating imageExportDPI would have no effect.

The higher this value, the more pixels will be exported and the larger the image files, but in return the images are better quality, and the user could zoom in further without losing quality.


Change the zero into a one to generate more compact CSS and HTML code (less comments and white space).


Set this to a zero (0) to avoid generating more than one EPUB folder per document. ePubCrawler will refuse to re-generate the EPUB folder unless you first delete it.


Set this to a zero (0) if you don’t want the first page to be used as the cover. You’ll need to take care of the cover image yourself in that case.


Set this to a one (1) if you don’t want the first page to be part of the EPUB. When used together with useFirstPageAsCover you can get the first page to be used as a cover without appearing in the EPUB as as page as well.


Further down in the config.ini you can find the fonts section, where you can define a font mapping. By adding one or more lines here you can map one or more InDesign font faces to specific CSS fonts.

The entries in the [fonts] section consist of a regular expression (regexp) and the info that any matching font needs to be mapped to – a comma-separated list of the CSS font-family, the font-weight, the font-style, and the font-size.

For more info, see the ‘Font Mapping‘ chapter.

The Template Folder

You don’t need to read this chapter about the ePubCrawlerTemplate in order to effectively use ePubCrawler. There is quite a bit to take in, and you might want to avoid the ‘information overload’ till later.

However, if you do read this chapter, you’ll be able to make ePubCrawler do much more.

The contents of the ePubCrawlerTemplate folder determine how the merged result looks. You’re free to tamper with this folder – any files or folders you add to it will be reflected in the merged result.

A placeholder is any combination of upper-case letters, underscores and digits, wedged between two dollar signs.

ePubCrawler makes extensive use of placeholders in many of the text files inside the ePubCrawlerTemplate folder.

You’re allowed to invent your own placeholders; e.g. you could use a placeholder $$MY_GREAT_PLACEHOLDER$$ in your .xhtml files.

Many placeholders are pre-defined for use with ePubCrawler, but you’re welcome to add your own.

You can change any of the template *.xhtml or *.css files inside ePubCrawlerTemplate to your liking. Whatever you change in them will be reflected in the resulting EPUB.

Some of the files and folders you’ll find in ePubCrawlerTemplate will get special treatment.

Special folders are: OEBPS, images. 

Special files are: config.inicontent.opf, $$PAGE_NAME$$.xhtml, $$PAGE_NAME$$.css, *.ncx, *.css, *.opf, *.xml, *.xhtml

Many of the special files (e.g. any file with a .css file name extension) will be inspected for placeholders by ePubCrawler, and any such placeholders will be replaced by some (possibly empty) text while the file is being processed.


Any file that gets copied into the subfolder called OEBPS  will affect the contents of the manifest for the EPUB. ePubCrawler will automatically keep track of any of the files it adds into the destination OEBPS folder as it builds the EPUB, and it will adjust the EPUB manifest accordingly.

OEBPS also contains the baseline config.ini and template files and template snippet files (e.g. $$PAGE_NAME$$.css, $$PAGE_NAME$$.xhtml, $$WORD$$.xhtml.snippet…).

Nor the config.ini, not these dollar-named files are not copied over to the destination OEBPS folder. Instead, they serve as templates for the XHTML and CSS output of ePubCrawler.

ePubCrawler will always first look in the selected ePubStyles subfolder for template files, snippets and an additional config.ini file.

You can configure the selected ePubStyles subfolder via the ePubStyle configuration from the config.ini.

When ePubCrawler cannot find a needed file in the selected subfolder, it will consult OEBPS as a fallback.

For example, most of the sample EPUB styles provided in the ePubStyles subfolder don’t have a $$WORD$$.xhtml.snippet file.

For all of those styles, the $$WORD$$.xhtml.snippet from OEPBS will be used.


If there is a folder called images then it will be used to store all the collected images.

While copying images across, ePubCrawler will rename the image files in order to make sure there are no possible clashes between same-name images.

For example, you might be linking to two totally different images both called Logo.jpg in your InDesign file, with original image each stored in a different folder. ePubCrawler will rename both files with a unique name as it copies them to the images folder.

If the images folder is missing, the images will be copied straight into the OEBPS folder instead.

content.opf :

The content.opf file is copied into the OEBPS folder. It is not listed in the manifest itself, as it contains the manifest. If you open the file content.opf inside the ePubCrawlerTemplate folder with a text editor, you’ll find some text:

 <spine toc="ncx">

The two placeholders $$MANIFEST$$ and $$SPINE$$ will be replaced by the manifest and the spine info calculated by ePubCrawler.

$$PAGE_NAME$$.xhtml, $$PAGE_NAME$$.css:

These files are the templates for the individual page files – each page in your InDesign document will be converted to an xhtml and a css file.

The $$PAGE_NAME$$ placeholder is replaced by the file name for the page: p1, p2, p3…

By adjusting these files, you can affect the generated pages. Feel free to add boilerplate stuff to either of these.

$$PAGE_NAME$$.css looks pretty much empty, except for a placeholder $$PAGE_CSS$$.

This placeholder will be replaced by the page-related CSS information generated by ePubCrawler – each frame on the InDesign page will become an entry inside the $$PAGE_CSS$$ block.

$$PAGE_NAME$$.xhtml has a bit more ‘meat’ to it – it looks almost like proper .xhtml, but also has a few scattered placeholders: $$PAGE_TITLE$$,  $$PAGE_NAME$$, $$PAGE_HTML$$,  $$PAGE_WIDTH$$,  $$PAGE_HEIGHT$$. These are all replaced by information extracted from the InDesign file.

*.ncx, *.css, *.opf, *.xml, *.xhtml:

Any files with these file name extensions are treated as text files, and are searched for placeholders that can be replaced.


This folder contains subfolders – one subfolder for each ‘style’ of EPUB that can be generated. Each of the subfolders contains a set of one or more snippets. Optionally, you can also have additional config.ini files in these subfolders.

Currently the following snippet files are supported:



You can override the default values for the various placeholders shown below by adding properly labeled text frames to the pasteboard.

For example, if you want to override the default value of the $$AUTHOR$$ string, you should create a text frame on the pasteboard, and assign it the script label META:AUTHOR.

The contents of this text frame will take precedence over the author information that was extracted from the XMP metadata assigned to the InDesign document.

Below a non-comprehensive list of placeholders that are automatically handled by ePubCrawler.

There are additional placeholders that have not yet been documented here. Consult the comments in the ePubCrawler.jsxbin script for a more up-to-date list.


The name of the author as extracted from the XMP info (see File – File Info… menu in InDesign).


The creator of the file as extracted from the XMP info (see File – File Info… menu in InDesign).


The date of the file (YYYY-MM-DD) as extracted from the XMP modification date info (see File – File Info… menu in InDesign).


The description of the file as extracted from the XMP info (see File – File Info… menu in InDesign).


This is replaced by the manifest (i.e. a list of all the files that went into the OEBPS folder, excluding the content.opf file).

Something like:

<item id="template" href="template.css" mediaType="text/css"/>
<item id="ncx" href="toc.ncx" mediaType="application/x-dtbncx+xml"/>
<item id="DSC_0050a" href="images/DSC_0050a.jpg" mediaType="image/jpeg"/>
<item id="DSC_0122" href="images/DSC_0122.jpg" mediaType="image/jpeg"/>
<item id="cssp1" href="p1.css" mediaType="text/css"/>
<item id="p1" href="p1.xhtml" mediaType="application/xhtml+xml"/>
<item id="cssp2" href="p2.css" mediaType="text/css"/>
<item id="p2" href="p2.xhtml" mediaType="application/xhtml+xml"/>
<item id="cssp3" href="p3.css" mediaType="text/css"/>
<item id="p3" href="p3.xhtml" mediaType="application/xhtml+xml"/>


This placeholder is replaced by a navigation map; it is currently used in the toc.ncx file. Something like this:

 <navPoint id="p1" playOrder="1">
 <text>My Great Title</text>
 <content src = "p1.xhtml"/>
 <navPoint id="p2" playOrder="2">
 <text>My Great Title</text>
 <content src = "p2.xhtml"/>
 <navPoint id="p3" playOrder="3">
 <text>Another Great Title</text>
 <content src = "p3.xhtml"/>


Total number of pages in the InDesign document


The height of the current page in pixels. Depends on the InDesign document setup.


CSS content for the current page. Each frame on the page is reflected by a CSS entry. If you want to determine what CSS ids should be used for each frame, you can assign script labels to individual frames. Any script labels that start with a ‘#’ are interpreted as CSS ids to be used by ePubCrawler.

ePubCrawler will auto-generate CSS ids for frames that don’t have such a script label.

In order to manager CSS ids in InDesign I’d like to recommend FrameReporter:

With FrameReporter, you can see all assigned script labels on the page in one go instead of having to click frame by frame and look at the Script Label palette (Window – Utilities – Script Label menu) – the screenshot below shows two images frames which have been assigned CSS id #ducks and #ducks_too:


The HTML ‘meat’ for the current page. ePubCrawler will try to set up the generated HTML so it approximates the philosophy behind InDesign styles, where one style can be ‘based on’ another.

InDesign paragraphs translate into <p>…</p> tags.

InDesign line breaks translate into <br/> tags.

Within the text between a set of <p>…</p> tags, there might be some <span>…</span> tags, to reflect InDesign styles assigned to the text.

Paragraph styles will be the outermost <span>. The corresponding CSS classes are provided in the $$SHARED_CSS$$.

If a paragraph style is using the ‘based on’ approach then nested <span> will be used to reflect this hierarchy. The innermost span will correspond to the actual paragraph style, and zero or more outer spans will reflect the ‘based on’ hierarchy of the styles in InDesign.

Within the paragraph text, any assigned character styles are also wrapped in nested spans. Again, the innermost span will correspond to the actual character style, and zero or more outer spans will reflect the ‘based on’ hierarchy for the character styles.


The name of the current page (e.g. p1, p2, p3…)


The page title. The default is an empty string, but ePubCrawler will try the following in order to get a page title:

First, if there is a text frame with a CSS id of #title then the contents of that frame will be used as the page title.

If no #title can be found, then ePubCrawler will look for a text frame with a script label META:PAGE_TITLE and if that frame can be found, its contents will be used for the page title.

It is allowed to have more than one text frame with the script label META:PAGE_TITLE  on a single spread: you can put such a text frame on the pasteboard above or below each separate page, and ePubCrawler will pick it up.


The width of the current page in pixels. Depends on the InDesign document setup.


A complete list of all $$WORD$$ and $$WORD_ID$$ that occur in the page being generated. See the sample inside



The copyright notice of the file as extracted from the XMP info (see File – File Info… menu in InDesign).


Shared CSS content. A CSS style for each of the paragraph styles and character styles in the document.

The ‘look and feel’ of the generated style sheets are determined by the $$PARASTYLE$$.css.snippet and $$CHARSTYLE$$.css.snippet files.

Paragraph styles have a CSS class name based on the InDesign paragraph style name, with a “P” appended.

Character styles have a CSS class name based on the InDesign character style name, with a “C” appended.

This placeholder is used in the default template.css file

$$SHARED_CSS$$ is a concatenation of $$SHARED_PARASTYLE_CSS$$ and $$SHARED_CHARSTYLE_CSS$$


A CSS style for each of the character styles in the document.

The ‘look and feel’ of the generated style sheets are determined by the $$CHARSTYLE$$.css.snippet file.

Character styles have a CSS class name based on the InDesign paragraph style name, with a “C” appended.

$$SHARED_CSS$$ is a concatenation of $$SHARED_PARASTYLE_CSS$$ and $$SHARED_CHARSTYLE_CSS$$


A CSS style for each of the paragraph styles in the document.

The ‘look and feel’ of the generated style sheets are determined by the $$PARASTYLE$$.css.snippet file.

Paragraph styles have a CSS class name based on the InDesign paragraph style name, with a “P” appended.

$$SHARED_CSS$$ is a concatenation of $$SHARED_PARASTYLE_CSS$$ and $$SHARED_CHARSTYLE_CSS$$


The name of the script currently running (i.e. ePubCrawler)


This is replaced by the spine info (i.e. a list of all the pages); e.g. something like:

 <itemref idref="p1"/>
 <itemref idref="p2"/>
 <itemref idref="p3"/>


The title of the file as extracted from the XMP info (see File – File Info… menu in InDesign). Currently synonymous with $$TITLE$$.


The title of the file as extracted from the XMP info (see File – File Info… menu in InDesign).


The version of the script currently running.


For use in the $$WORD$$.xhtml.snippet file. $$WORD$$ is repeated over and over, and replaced by the consecutive words from the text. It can be used in conjunction with the $$WORD_ID$$ placeholder, which contains a unique CSS id for each word. For example by setting the contents of the $$WORD$$.xhtml.snippet file to

<span id="$$WORD_ID$$">$$WORD$$</span>

every word will be wrapped in a separate <span> with a unique ID assigned. Also see $$WORD_ID$$ and $$PAGE_WORD_LIST$$


For use in the $$WORD$$.xhtml.snippet file. The $$WORD_ID$$ placeholder contains a unique CSS id for each word. For example by setting the contents of the $$WORD$$.xhtml.snippet file to

<span id="$$WORD_ID$$">$$WORD$$</span>

every word will be wrapped in a separate <span> with a unique ID assigned. Also see $$WORD$$ and $$PAGE_WORD_LIST$$

Other placeholders

Any other placeholders are replaced by the content of a text frame on the InDesign document’s pasteboard.

For example, the placeholder $$TITLE$$ is replaced by the contents of a text frame with the script label META:TITLE.

Similar, $$PAGE_TITLE$$ is replaced by the contents of a text frame META:PAGE_TITLE.

In order to stash meaningful information into placeholders like $$TITLE$$, $$AUTHOR$$… you’ll need to create additional text frames in your InDesign document.

Put these additional text frames somewhere on the pasteboard, and assign them a script label that starts with the prefix META:, followed by the placeholder.

Don’t add any spaces to the script label.

This mechanism also works for your own placeholders. If you have used a placeholder $$MY_OWN_PLACEHOLDER$$ somewhere in one of the template text files, it will be replaced by the contents of the text frame labeled META:MY_OWN_PLACEHOLDER.


For advanced users, there is also support for formulas. Unlike placeholders, which are wedged between $$ and $$, formulas are wedged between $($ and $)$.

Many of the sample snippets rely on formulas to do their magic.

For example, the sample EPUB style plainpercentages uses formulas to calculate the CSS position and size percentages.

Another example: the sample $$TEXT_FRAME$$.css.snippet files all use formulas to account for the text inset applied to text frames in InDesign.

Between those two  $($ and $)$ ‘markers’ you can use any ExtendScript formula, and also refer to any of the placeholders.

You could have a CSS snippet in $$IMAGE_FRAME$$.css.snippet that said:

left: $($ FRAME_XPOS_PIXELS + 10 $)$px;

and that would take the frame x position in pixels, and add 10.

You can also use formulas to access ExtendScript info – for example, the formula

$($ (new Date()).toString() $)$

is replaced by the current date and time.

Have a look at the sample $$IMAGE_FRAME$$.css.snippet in the plainpercentages subfolder of the ePubStyles folder.

You’ll see things like:

left: $($ Math.round(100.0 * FRAME_XPOS_PIXELS / PAGE_WIDTH + 0.5) $)$%;

which is a formula that calculates a percentage from the frame’s x-position and the page width. Math.round() is a JavaScript function used for rounding.

If, for a certain frame, FRAME_XPOS_PIXELS were 60, and PAGE_WIDTH were 200, then the above expression will cause the following output:

left: 30%;

for that particular frame.

There are more examples in the various snippet files.

Font Mapping

ePubCrawler has a font mapping mechanism. By default, nothing is mapped.

That means that the contents of the template.css file will be incorrect: the font-family names are straight copies of the InDesign font names, and probably won’t make sense in CSS.

To help with setting up some sensible font info in the CSS, ePubCrawler allows you to set up a font mapping.

First, you’ll do a dry run: convert your InDesign document to an EPUB folder, after setting the desired configuration options in the config.ini

Open the output folder, go into the OEBPS folder, and open template.css in a text editor.

Now inspect this file, and take note of all the various fontMatchString you see in the comment blocks inserted in each CSS style.

fontMatchString: Mister Pablo Regular,12
fontMatchString: Adelaide Regular

These fontMatchString are calculated by ePubCrawler from the font information it is given by InDesign.

This font information is quite variable in quality and quantity, and depends on the font type, the info available in the font file, and other factors. For some fonts, ePubCrawler has access to a lot of info. For other fonts there is very little info.

ePubCrawler will make do with whatever info it gets from InDesign and it will do its best to calculate some identifying font name. It will then append a comma and the point size (if that it is applicable and available), and the result is used as the fontMatchString.

These fontMatchString can then be mapped onto CSS font info via entries in the config.ini file.

You could add these mapping strings to the global config.ini file in the OEBPS folder if you wanted to.

However, it is better to create a new EPUB style and put a small config.ini file inside the corresponding ePubStyles subfolder, so the mapping can be made specific to one particular EPUB style.

Open a text editor, and either create a new file called config.ini (to be stored inside the ePubStyles subfolder) or open the global config.ini file from the OEBPS folder.

Make sure the config.ini has a [fonts] section – if necessary start by adding a [fonts] line into the file.

Below the [fonts] line, you will add one or more lines for mapping fonts. Each of the lines is of the form:

<<regexp>>=<<css font info>>

The <<regexp>> stands for a regular expression that will be matched against the various fontMatchString you found in the template.css file.

The <<css font info>> stands for set of up to four comma-separated entries: a font-family, optionally followed by a font-weight (either bold or normal), optionally followed by a font-style (either italic or normal), optionally followed by a font-size (with a CSS unit appended – e.g. 12px).

For example, the following mapping:


would map any font string to a font-family Times

A mapping like

Mister Pablo Regular,12=Arial,bold,normal,14px

would map the fontMatchString “Mister Pablo Regular,12” onto a font-family of Arial, with a font-weight of bold, a font-style of normal, and a font-size of 14px.

If you wanted to map all fontMatchString  irrespective of point size, you’d instead write:

Mister Pablo Regular.*=Arial,bold,normal

i.e. use a regular expression to match any point size.

Font mappings are processed top-to-bottom, until a match is found. That means that you can add a ‘catch-all’ regular expression to the bottom of the list which catches all not-yet-mapped fontMatchString.

Below a sample config.ini that you could put into an ePubStyles subfolder:

Mister Pablo Regular,12=Arial,normal,normal,14px
Mister Pablo Regular.*=Arial,bold,normal

This little table would map all occurrences of “Mister Pablo Regular”, 12pt onto “Arial”, 14px. Any other size of “Mister Pablo Regular” is mapped onto “Arial”, bold. Any other fonts are mapped to “times,serif”.


In addition to the written info here, we also have some more info in the ‘Videos‘ section.

First, download the .zip file with the script (see top of this page).

Put the downloaded file on your desktop first.

Then extract the contents of the .zip file.

On Macs, the file might auto-decompress. If not, double-click the ePubCrawler….zip file.

On most Windows installations, you can right-click ePubCrawler….zip and select Extract All… from the contextual menu.

Inside the folder ePubCrawler.x.x.x, where x.x.x is one or other version number you should find the ePubCrawler.jsxbin file.

Also look for a folder called eCanCrusher. This eCanCrusher folder does not need to be installed into your InDesign folder (but no harm would be done if you happen to copy it along).

Open the eCanCrusher folder and unzip either or The contents of these zip files is a small drag/drop utility that converts a naked EPUB folder into an .epub file. You can move the contents of the unzipped eCanCrusher application to your desktop for easy access.

On Windows you need to move both the eCanCrusher.exe and the eCanCrusher Libs folder that sits alongside it.

Now go back to the ePubCrawler.x.x.x folder and find the file called ePubCrawler.jsxbin.

Depending on how your workstation is configured, you might or might not see the .jsxbin file name extension.

Once you’ve located the ePubCrawler.jsxbin file, make sure you also notice a folder ePubCrawlerTemplate right next to it.

You can now start InDesign, and bring up the Scripts palette via the Window – Utilities – Scripts menu item. Right-click (or option-click on Mac) the User entry on the palette to bring up the contextual menu.

If you have sufficient administrative privileges on your computer, you could just as well select the Application entry. If you’re unsure, pick User instead; that should work for everyone.

Select the contextual menu item Reveal in Explorer (Windows) or Reveal in Finder (Mac).

A folder should open in Explorer or the Finder. Double-click the folder named Scripts Panel to open it.

Once you have the Scripts Panel folder open, you can drag the ePubCrawler.jsxbin file AS WELL AS the ePubCrawlerTemplate folder into this Scripts Panel folder. Make sure to drag over TWO items!

Close the windows afterwards.

Switch back to InDesign. If you did it right, the script should now appear on the Scripts palette, under the entry you picked (either User or Application). You might need to click the disclosure triangle to open it up.

Double-click the ePubCrawler.jsxbin entry to run the script.

That’s it! The script is now installed and ready for use! Have fun!

Please send feedback and bug reports to [email protected], and follow @zwettemaan on twitter – there will be regular updates with improvements, so you want to stay tuned in.


I’ve started recording some videos to help getting started with ePubCrawler: click the links a little further below to open the video pages.

I also highly recommend Anne-Marie Concepción’s ‘Creating a Fixed-Layout EPUB’ on

Anne-Marie’s tutorial will give you the knowledge you need to finish the rough-and-ready EPUB generated by ePubCrawler.

The YouTube videos below are work-in-progress: I’ll try to gradually extend this collection. Also keep in mind that some of these have been recorded with earlier versions of ePubCrawler, and things might have slightly changed since.

1. Installing ePubCrawler

2. Running ePubCrawler

3. Configuring ePubCrawler

4. Font mapping with ePubCrawler

5. Using Templates and Snippets with ePubCrawler

6. ePubStyles in ePubCrawler

Essential Links

Liz Castro’s blog. Liz’s books on EPUB are required lecture – you’ll find links to them on her blog:

Anne-Marie Concepción’s Lynda tutorials: 



This software has been distributed as donationware over the course of 2012 and 2013. It is currently available on an as-is basis. It is free to use, but there won’t be any more updates, as it is being superseded by Crawler+EPUB (

If you need any help with setting up or customizing ePubCrawler to match your workflow, feel free to inquire about hiring me to help you or train you; contact [email protected]


There is a licensing limitation – here’s the deal: when using ePubCrawler you must leave the comments like

<!-- Generated by ePubCrawler 0.1.1 
( on Tue Jun 26 2012 23:46:56 GMT+1200 -->


/* Generated by ePubCrawler 0.1.1 
( on Tue Jun 26 2012 23:46:56 GMT+1200 */

in the CSS and HTML. You’re not allowed to take them away.

Also, when you build your own ePubCrawler templates, I ask that you make sure these comments get added to the generated e-book. You can copy the necessary bits of code from the sample templates.

Using ePubCrawler to generate EPUB that are not marked with such comments is considered a breach of the licensing agreement.


December 27, 2014: The donation-ware program has been stopped for lack of buy-in. ePubCrawler will be superseded by a new commercial product called Crawler, which will have a FL-EPUB export personality. More info will become available at

Version 0.2.5: Released December 13, 2012.

– Fixed bug where special characters were not correctly translated in CS5 and higher.
– Fixed bug where hyperlinks in the text that had a style applied ended up with the </a> and </span> swapped, resulting in invalid XHTML.

Version 0.2.4: Released December 11, 2012. Sincere thanks to JC (@jctremblay) and Brani (@branislavmilic) for the extensive testing and bug reports!

– Now handles current page number markers.
– Fixes a bug in 0.2.3 where ‘[Paper]’ was mapped to black instead of ‘no color’
– Fixes a bug in 0.2.3 where the last pages of a document with an even number of pages got muddled up.
– Added a new script label ‘tag’: if you add a line with the word bitmap to the script label of a text frame, then that frame will be exported as a JPEG instead of text.
– Script labels with multiple lines are now properly interpreted (e.g. you can provide a CSS #id on one line, and the word bitmap or ignore on a second line…)
– While ePubCrawler is processing, the output folder is temporarily renamed to ePubCrawler_IN_PROGRESS, and renamed once processing is complete. This remedies the issue where some users ‘grabbed’ the output folder before ePubCrawler was finished processing, leading to an incomplete epub folder.
– Added support for the <guide> section in the content.opf. Add two lines to a page item’s script label: guidetype:… and guidetitle:… (e.g. a sample script label could look like this:

guidetitle:The Table Of Contents

This would enforce a CSS id of #MyOwnID for the frame, force bitmap export of the textframe, and make this into a <guide> entry in the content.opf.
– Snippetize content.opf, toc.ncx and a whole host of ‘inner’ XHTML. Apart from some minor elements, all XHTML output is now driven by template snippets that are user-adjustable.
– Save before, revert afterwards: version 0.2.3 and earlier kept track of any changes they made, and reverted them after the process finished. Version 0.2.4 instead will only work when the document is saved before the process starts, and it will revert at the end of the process. This allows 0.2.4 to make destructive changes to the document with relative impunity, as all these changes vanish when the document is reverted at the end.
ePubStyles subfolders have been restructured, and now have ‘OEBPS’ and ‘META-INF’ subfolders, and these can be used to ‘override’ or add to the default info
– Improved a lot of the paragraph formatting (e.g. margins).
– Fixed issue where punctuation at the end of paragraph was forced into a separate <span>
– Added rounding to various formulas.jsx files. This hopefully remedies unrounded pixel values.
– Empty text frames should now be better handled.
– Now should handle ‘external’ hyperlinks (http:, mailto:).
– There is a new option addSoftHyphens in config.ini. Default is 0 (off). Set this to 1, and ePubCrawler will find all hyphenation points in the text and export them as discretionary (soft) hyphens. The XHTML text becomes less readable, but will have a nicer ‘fit’ because of the potential hyphenations.
– Cleaned up a number of issues in CS3 – 0.2.4 should work better with CS3 than previous versions. However, CS5 or higher is recommended. CS3 is a ‘best effort’, but it’s becoming clear that eventually some features won’t be supportable in CS3.
– Many other small fixes.

Version 0.2.3: Released November 7, 2012. Sincere thanks to JC (IDUG Montreal) for the extensive testing and bug reports!

– Changed behavior of $$PAGE_TITLE$$ placeholder, so information now ‘cascades’ down. First, it will look near or on the page for a text frame with script label $$PAGE_TITLE$$, and use its content for the HTML page title (between <title>…</title>).
If that cannot be found, it will use the XMP document title info instead.
If that is empty, it will use the InDesign page name instead (section name + page number).
$$PAGE_TITLE$$ is used in the <title> tag on the default page snippets provided.
– Changed metaInfoLabelPrefix/metaInfoLabelSuffix in the config.ini from “META:”/”” to “$$”/”$$”, so InDesign script labels assigned to text frames whose contents provide meta-info now look more related to the placeholders they determine in the snippets.
For example, the text content of a text frame with an InDesign script label $$PAGE_TITLE$$ will now automatically determine the value for the $$PAGE_TITLE$$ placeholder.
– The InDesign color [Black] is now special-cased so it maps to CSS #000000. Other colors are converted through InDesign’s color mapping mechanisms in order to map from non-RGB to the RGB color model.
– Unused paragraph and character styles are not exported to the EPUB any more.
– InDesign’s leading is converted to CSS line-height.
A new setting, adjustForLeadingChanges, is now available in the config.ini.
Setting it to 1 makes ePubCrawler attempt to preserve the ‘look and feel’ of the InDesign text by manipulating the margin-top of some paragraphs.
CSS distributes the extra white space from the leading evenly above and below the text, whereas InDesign moves all the extra white space above the text, which makes the text shift on conversion from InDesign to HTML+CSS.
With adjustForLeadingChanges ePubCrawler will attempt to compensate for this difference in handling of leading.
– ‘White space’ (empty) paragraphs in InDesign are now translated to <p…>&nbsp;</p> in HTML.
– Cleaned up superfluous <span> in the generated HTML text.
– Now nested InDesign para styles are mapped to a list of space-separated classes applied to the <p> tag instead of using a <p> with nested <span>.
– Converted InDesign frame rotation angle into a -webkit-transform: rotate(…). 
If you don’t want this you need to adjust the frame CSS snippets and remove this entry.
ePubCrawler does not yet support any other transformations – only rotation is currently converted over.
– Added support for ‘first line indent’.
– Justified InDesign text now maps correctly to justified CSS text. There is no differentiation between left, right or center-justified text – all three map to CSS justified text.
– Added support for space after/space before para attribute.
– Preserve InDesign soft hyphens and non-breaking spaces as &shy; and &nbsp;
– Corrected error where overflowed text was appearing on the background image.
– Corrected script crash when anchored objects were present. There is no real support to do anything sensible with anchored objects yet, but at least, they won’t cause a script crash any more.
– Corrected calculation errors in the mapping of border width, text inset.
– Changed line endings in various text files to Windows CRLF so the files can be viewed with Notepad on Windows.

Version 0.2.2: Released October 25, 2012

– Added progress dialog
– Added imageHandling=4, where text is exported twice: once as a bitmap on the background (for visual accuracy) and a second time in hidden overlayed text frames (‘visibility: hidden’). This is an attempt to combine accurate text rendering with searcheability.
– Fixed bug causing swatch [Paper] to show up as black.
– Partial support for back-to-front priority: z-index for background image is now -1, z-index for other elements is now 0.
– Added extra newline in CSS comments after first /* to resolve issue with some readers
– Added ePubStyle percentagesbkg to help with KF8 Fixed Layout
– Fixed issue where % values in percentages ePubStyle had 1 added to them (e.g. 0% was shown as 1%, 100% was shown as 101%).
– Added body{…} entry to template.css
– Removed superfluous “./” from image paths
– Added ignoreLayers setting to config.ini. It is a GREP expression to suppress layers by name.
– Added ignoreInvisibleLayers setting to config.ini. Default is 1; setting it to 0 causes ePubCrawler to also export content on invisible layers.
– Added double quotes around font-family names in CSS.
– Fixed issue with the CSS mapping of character styles that have only style info, and no associated font.
– Fixed: singleCSSFile = 1 was erroneously adding references  to non-existent page-based CSS files to the xhtml pages.
– Fixed small issues in various snippets and templates

Version 0.2.1: Released August 6, 2012

– Added support for colors (applied to text, frames, frame borders).
– Renamed the ePubStyles provided to better describe what they do.
– The config.ini file can now reside next to the ePubCrawler.jsxbin file so you don’t need to ‘dig’ into the OEBPS folder to find it.
– Added a new setting singleCSSFile to the config.ini. Setting this to 1 forces ePubCrawler to combine all CSS into a single file (instead of generating a separate CSS file for each page).
– This version avoids CSS constructs that caused Adobe Digital Editions to crash on the generated EPUB.
– Changed the default ePubStyle so it puts the images in <img> tags inside a <div> tag instead of using CSS background images. Switch to the imagesbkg ePubStyle to make images appear as CSS backgrounds.

Version 0.2.0: Released July 29, 2012

– Fixed issues with spaces in font file names
– Fixed EPUB verification issue with <p> inside <span>

Version 0.1.9: Released July 29, 2012

ePubCrawler now honors ‘manual’ style overrides (i.e. style overrides that are not part of a named character or paragraph style). This behavior can be influenced by changing the ignoreInlineStyling and ignoreOverrideParaStyling settings in the config.ini file.

You’ll get better results (i.e. less complexity in the XHTML files) if you clear up any manual overrides in InDesign and then set both ignoreInlineStyling and ignoreOverrideParaStyling to 0.

ePubCrawler  will now copy .ttf and .otf font files into the EPUB if it is able to. It will add the corresponding @fontface CSS entries to the templace.css file. It will also add the the necessary entries in to the manifest in the content.opf file.

This behavior is controlled by the setting copyAllFonts in the config.ini file.

Alternatively, for a more controlled set-up, you can set copyAllFonts to 0.

Then create or copy a custom subfolder inside the ePubStyles folder

Let’s say you call the folder mycustomstyle. Create a fonts folder inside the mycustomstyle subfolder. Finally, set ePubStyle in config.ini to the name of the folder, i.e. mycustomstyle.

Any fonts in this ePubStyle-specific fonts folder will be copied across to the OEBPS/fonts folder in the EPUB.

Make sure you respect the font licensing restrictions of the fonts you have available.

ePubCrawler now sets the text-align: CSS attribute.

Version 0.1.8: Released July 21, 2012

– New option in config.ini: imageHandling. This option replaces reuseImages.
Setting this to 0 (zero) will make ePubCrawler attempt to use any linked JPEG files as-is instead of exporting their visible areas from the various InDesign frames. imageHandling = 0 will generate less linked files when a single image is placed multiple times in an InDesign document.
Setting imageHandling to 1 will make ePubCrawler export images to JPEG on a frame-by-frame basis. Possibly there is more than one exported image file per frame when an image spans multiple pages on a spread.
Setting imageHandling to 2 will make ePubCrawler export whole pages to JPEG, after removing all text, so there is one big ‘background’ JPEG per page. This can be helpful when trying to convert image effects from InDesign to EPUB as it will retain any special effects (e.g. drop shadows, blends) that have been applied in InDesign.
Setting imageHandling to 3 will make ePubCrawler do both frame-by-frame and whole page backgrounds (i.e. it is a combination of settings 1 and 2). This gives you more freedom during the editing phase of the EPUB.

Version 0.1.7: Released July 21, 2012

– New options in config.ini:
pageNamePrefix (affects the generated page names, used for naming .xhtml files and generating CSS ids).
reuseImages (can force ePubCrawler to use linked JPEG files as-is instead of re-exporting the images from the InDesign document).
extraComments (add extra info into the generated output, explaining the what and how of particular constructs).
flattenedStyles (disable the mechanism ePubCrawler uses to mimic the ‘based on’ feature for InDesign paragraph and character styles).
paraIdPrefix (prefix to use for the unique paragraph CSS ids – see ePubStyle plainpixelsreadaloud)
lineIdPrefix (prefix to use for the unique line CSS ids – see ePubStyle plainpixelsreadaloud)
wordIdPrefix (prefix to use for the unique word CSS ids – see ePubStyle plainpixelsreadaloud)
For more info: view the config.ini from the OEBPS folder in a text editor.

– Added support for writing your own custom ExtendScript formulas by means of a formulas.jsx file. Check formulas.jsx in the OEBPS folder for an example (e.g. amongst others, it defines a new placeholder $$TODAYS_DATE$$).

Version 0.1.6: Released July 14, 2012

– Added an option usePageNames to config.ini to use InDesign page names instead of page indices for the various page identifiers. For example, if you use roman numerals to number pages, you can now opt to get file names like xii.xhtml instead of p12.xhtml. Also allows easier merging of EPUB folders if your book is spread over multiple .indd documents.
– Fixed bug that caused many special characters (e.g. em-dash, en-dash) to disappear from the output.

Version 0.1.5: Released July 13, 2012

– Bug fix related to fonts

Version 0.1.4: Released July 11, 2012

– Bug fix related to fonts

Version 0.1.3: Released July 11, 2012
ePubCrawler is now to be configured through one or more config.ini files.

The main config.ini file is located in the OEBPS folder in the ePubCrawlerTemplate folder. This main config.ini has many settings, including the name of the ePubStyle to use.

Individual ePubStyle subfolders can have additional, smaller config.ini files which override zero or more settings in the main config.ini on a per-ePubStyle basis.

Open the config.ini file in OEBPS in a text editor for more info; the file is heavily commented.

For more info, see  ‘Customizing ePubCrawler.

ePubCrawler now has a font mapping mechanism that allows you to predefine how various InDesign fonts should be mapped to CSS.

The mechanism uses regular expressions, so it is possible to map multiple font variants in a single line of the config.ini. You can inspect the config.ini inside OEBPS for more info. For more info, see the ‘Font Mapping‘ chapter.

– Converted from .jsx to .jsxbin format. Donations are very thin, to put it mildly, so I am gradually starting to protect the code as a preparation for converting to a ‘payware’ product.

Version 0.1.2: Released July 3, 2012

– Added new image handling option which greatly improves the usefulness for the plainpixels and plainpercentages EPUB styles.
Images can now be resampled to a pre-set resolution. Images that ‘saddle’ two pages are exported as two separate image files.
– Fixed issues in CS3.

Version 0.1.1: Released June 26, 2012
– Fixed problem with interpretation of certain fonts.
– Corrected issues with InDesign to CSS style mapping.
– Converted ‘magical’ placeholders used in previous versions (e.g. $$FRAME_XPOS_PERCENT$$) into $($ …formula… $)$. The snippets become a bit more complex, but also much more flexible.

Version 0.1.0: Released June 26, 2012
– Fixed bug in eCanCrusher that caused it to generate incorrect EPUBs (it was compressing the mimetype file instead of leaving it uncompressed).

Version 0.0.9: Released June 25, 2012
– Continuing to templatize. Now ePubCrawler has placeholder-based templates for all of the InDesign paragraph and character style sheets translations.
– Added support for formulas in placeholders. Instead of $$PLACEHOLDER$$ you can now also use formulas wedged between $($ and $)$ – e.g. $($ FRAME_XPOS_PIXELS + 10 $)$. If you know ExtendScript or JavaScript: you can also use expressions from those realms (e.g. $($ (new Date()).toString() $)$ is allowed).

Version 0.0.8: Released June 23, 2012
– ePubCrawler now also includes eCanCrusher – a small drag/drop tool that converts an EPUB folder into an .epub file. No more command line acrobatics with zip!
– Continued to templatize. Now ePubCrawler has placeholder-based templates for individual frame XHTML and CSS, and even for individual words, so with the proper template you can assign individual CSS ids to each word.
– Fixed a problem that could cause InDesign to crash.
– Better handling of multi-frame text stories.
– Started on support for read aloud eBooks. This is not complete yet!

Version 0.0.7: Released June 15, 2012
– ePubCrawler now consults the XMP metadata and extract info like author, title,… and use it for the corresponding placeholders like $$TITLE$$, $$AUTHOR$$ and so on.
– Can use a JPEG export of the first page of the document as a cover image.
– Generated EPUB folder now passes validation with epubcheck-3.0b5.

Version 0.0.6: Released June 15, 2012
– Properly translate <, >, & into &lt;,  &gt;&amp;
– Fixed various small but lethal issues in template files which made the resulting output to be invalid for EPUB.
– Widened support: now works with InDesign CS3 and upwards.
Planned enhancements:
– ePubCrawler should consult the XMP metadata and extract info like author, title,… and use it for the corresponding placeholders like $$TITLE$$, $$AUTHOR$$ and so on. 

Version 0.0.5: Released June 14, 2012
– Fixed issue with char/para style translations.
– Now properly translates paragraph returns (<p></p>) and line breaks (<br/>).
– Image names now include the name of the page they appear on first (e.g. p1_DSC_0531.jpg first appears on p1.xhtml).
– META-INF folder was broken in 0.0.4 – now fixed.
Known issues in this version:
– Currently, ePubCrawler does not properly handle special characters like <, >, & in the text of the document. Next version will properly convert these to &lt;,  &gt;, &amp; etc…

Version 0.0.4: Released June 14, 2012
– First ‘official’ release.