Embedding Fonts in Your EPUB

You can embed fonts into your EPUB by providing a manifest that lists the font files to be embedded.

While embedding fonts in EPUBs is generally not recommended because of interoperation and file size concerns, if you need to embed fonts in your EPUB you can do so.

To embed fonts you define a font manifest document that lists the fonts to be embedded and then specify the URI of the manifest as a runtime option to the EPUB transform (epub.font.manifest Ant parameter). The fonts listed will be copied to the temporary output location and included in the EPUB file. You can also specify the location within the EPUB package where the fonts will be stored, which by default is the directory named "fonts" (epub.fonts.output.dir Ant parameter).

You can optionally obfuscate any fonts by specifying "obfuscate" for the @@obfuscate attribute and setting the runtime Ant property epub.obfuscate.fonts to true (epub.obfuscate.fonts Ant parameter). By default fonts are not obfuscated and fonts marked for obfuscation are not actually obfuscated unless you specifically turn obfuscation on with the epub.obfuscate.fonts Ant property. This allows you to generate EPUBs with unobfuscated fonts for testing or for use with readers that do not support obfuscation without having to modify the font manifest.

You must create the appropriate @@font-face rules in the CSS style sheets used for the HTML content. The @font-face rules must reflect the location of the fonts in the final EPUB package, not their source location. For example, if the fonts are stored in a directory named "my-fonts" but packaged in the default "fonts" directory, then your CSS needs to reflect the "fonts" directory, not "my-fonts". See examples of @@font-face rules below.

You can generate a CSS file containing the @font-face rules for the fonts in the manifest by setting the epub.generate.css.font.rules Ant parameter to "true" and including configuration details for the @font-face rules in the font manifest for each font. You must separately create a reference to genenerated CSS file in one of the CSS files included in the EPUB.

The Font Manifest File

The font manifest file is an XML document that lists the fonts to be embedded. The grammar for the document is the font-manifest RELAX NG grammar included in the org.dita4publishers.doctypes plugin. The plugin also includes a template font manifest document.

A font manifest file looks like this:

<font-manifest>
    <title>EPUB Font Manifest</title>
    <desc/>
    <font-set>
      <title>Base font set</title>
      <desc/>
      <font uri="Papyrus.ttc"/>
    </font-set>
</font-manifest>

You use the  element to specify the relative URI of a font to embed. The URI is relative to the location of the font manifest file itself. In this example, the font manifest document must be in the same directory as the referenced font ("Papyrus.ttc").

You group the  elements into one or more <font-set> elements. For now there is no special functionality associated with font sets but they may be used in the future to enable conditional selection of fonts at runtime if anyone needs that level of control or convenience.

The <title> and <desc> elements are just for documentation purposes.

If you need to obfuscate a font when it is embedded you can specify the @@obfuscate attribute on  or <font-set> with the value "obfuscate". Fonts marked "obfuscate" will be obfuscated when obfuscation is turned on at EPUB generation time (obfuscation is off by default).

For example:

<font uri="Papyrus.ttc" obfuscate="obfuscate"/>

You can add additional details to the font manifest to configure the generation of CSS @font-face rules.

Using Fonts from CSS Style Sheets (@font-face)

To use embedded fonts you must include @font-face rules in your CSS style sheets in order to associate font family names to the font files in your EPUB. There is no automatic matching of font-family values to font files. The EPUB generation process does not do any manipulation of CSS files for you, although you can generate the @font-face rules at runtime using configuration in the font manifest.

A typical @font-face rule looks like this:

@font-face {
  font-family : Arial;
  font-weight : bold;
  font-style: normal;
  src : url(../fonts/Arial-BoldMT.ttf);
}

The font-family value is the name that will be used on font-family entries elsewhere in the CSS. The src value is the relative URL of the font file as it is packaged in the EPUB, relative to the location of the CSS style sheet file as packaged in the EPUB.

In this example, the style sheet must be in a directory next to the fonts directory, maybe a directory named css.

You need one @font-face rule for each different combination of font properties (font weight, font style, etc.) for a given font family.

See the CSS specification or a good CSS guide for details.

Generating @font-face Rules

You can optionally request the generation of a CSS file containing @font-face rules for the fonts in the font manifest.

If you specify "true" for the epub.generate.css.font.rules Ant parameter the EPUB transform will generate a CSS file containing @font-face rules for each font in the font manifest. The CSS file is generated in the configured font output directory. The default name of the generated CSS file is "fonts.css". To use this file you must separately add an @import rule to the main CSS file you want to use the fonts from, e.g. @import "../fonts/fonts.css";.

By default you get one @font-face rule for each font in the font manifest. However, you can add <font-face> elements within a  element to produce multiple result @font-face rules for the same physical font file:

<font-manifest>
    <title>Fonts for My EPUB</title>
    <font-set css-filename="fonts.css">
      <title>Base font set</title>
      <desc>This is the description.</desc>
      <font uri="Avenir-Black.ttf" css-font-family-name="Avenir">
        <css-rules>
          <font-face font-weight="bold" font-style="italic"/>
          <font-face font-style="italic"/>
           <font-face font-weight="bold" 
            font-stretch="condensed"            
          />
        </css-rules>
      </font>
  ...
</font-set>

The @@css-filename attribute on <font-set> specifies the filename to use for the generated CSS file. The default is "fonts.css". The location of the file is relative to the configured fonts directory.

On the  element you specify the @@css-font-family-name to set the value of the "font-family" property in the @font-face rule. The default is the filename of the physical font with the extension removed.

The <css-rules> element contains zero or more <font-face> elements.

Each <font-face> element represents a separate @font-face rule. The <font-face> element takes attributes corresponding to the properties allowed (or expected) on @font-face rules. Each attribute will be used to generate the corresponding property in the @font-face rule. Because CSS is inherently extensible and constantly being updated, there is no checking on the actual attributes you use (although the RELAX NG grammar for the font manifest defines a specific set of attributes reflecting the current set of defined font properties as an aid in authoring font manifest files).