What’s in this Document:
- Elements of the ePub spec that Kobo does and does not support.
- Features of the five Kobo reading platforms.
- Recommendations on file production and testing for content creators.
- ePub Versions Kobo Supports
- Kobo Reading Platforms
- Kobo Devices
- Kobo Recommends Initial ePub Check
- Sideloading for Testing Purposes
- Digital Rights Management (DRM)
- Placing Images Properly
- Cover Images
- Scalable Vector Graphics (SVG)
- Table of Contents (ToC)
- OPF
- CSS
- Supported Fonts
- Obfuscated Fonts
- Embedded Fonts
- Languages
- [Right to Left Page and Text Direction] (#right-to-left-page-and-text-direction)
- Footnotes/Endnotes
- Fixed Layout
- SMIL
- Image-Based FXL Reader
- Multimedia Support / Media Overlays
- JavaScript Support
- MathML
- Fallback Statements
- ePub Previews
- Tables
- Limitations and Maximums
- [Support Grid] (#support-grid)
- Questions?
Kobo supports ePub, the universal open standard eBook format maintained by the Independent Digital Publishing Forum (IDPF). The current version is ePub 3 but Kobo still supports its predecessor, ePub 2.0.1.
Any ePub file sent to Kobo will be made available on all of Kobo's reading platforms with the exception of ePub2 Fixed Layout content which is not available on Desktop or eInk:
| Platform | ePub2 Reflowable | ePub2 FXL | ePub3 Reflowable | ePub3 FXL |
|---|---|---|---|---|
| Android | Y | Y | Y | Y |
| Desktop | Y | N | Y | Y |
| eInk | Y | N | Y | Y |
| iOS | Y | Y | Y | Y |
| Windows 8 | Y | Y | Y | Y |
| Sony eReader | Y | N | Y | Y** |
| Kobo Vox* | Y | Y | Y | N |
| Blackberry* | Y | N | N | N |
| Original Kobo/Kobo WiFi | Y | N | N | N |
*The Kobo Vox and Blackberry apps both run older versions/ports of the Android app and will not be updated.
**Fixed Layout content display on Sony Readers is dependant on the capabilities of Adobe SDK. As a result the display of Fixed Layout content may not always match the display across other Kobo reading platforms.
The ePub 3.0 spec is based on HTML5 and CSS3, adhering to the most recent versions. Content creators are advised to review the HTML5 and CSS3 reference profiles because changes to them could impact file production.
Kobo supports a subset of elements from the ePub 3.0 spec. The following covers which elements are supported across Kobo’s reading platforms.
Kobo does not accept .mobi, KF8, PDF or any format outside of ePub that may be used to format eBooks.
- eInk/EPD — Kobo eInk devices (Aura, Glo, Touch)
- Desktop — the Kobo desktop app for PC and Apple Computers
- Android — all Android devices running the Kobo app including all Kobo Arc versions
- iOS — iPad, iPhone and iPod Touch
- Windows 8 — all tablets, smartphones and computers running Windows 8.
Android:
- Arc 7 SD
- Arc 7 HD
- Arc 10 HD
eInk:
- Glo HD
- Aura H2O
- Aura
- Aura HD
Android:
- Arc (original)
- Vox
eInk:
- Glo
- Kobo Mini
- Touch
- Kobo WiFi
- Kobo1
The Kobo CMS does not use a built in ePubCheck. To detect errors in ePubs, the IDPF provides both a web validation tool and a desktop application. Kobo cannot guarantee that files that fail ePubCheck will render correctly across its reading platforms. So ePubs should be validated using the most recent version of ePubCheck prior to distribution.
The Kobo Content Management System will neither reject those files that fail ePubCheck nor send reports to their publishers. However, if any rendering or performance issues harm the user experience, the files may be flagged for, and then failed in, the Kobo content QA process.
Kobo recommends content creators remove any files not listed in the OPF document, as suggested by the validator. Leaving these files in the ePub can cause unexpected behaviour that may result in failing QA test results.
Kobo encourages the testing of content on all its reading platforms by sideloading. Content should display identically whether sideloaded or downloaded to a device from the Kobo store. Instances where this is not the case can be reported to [email protected] and the epub in question will be logged for investigation. The only present exception applies to ePubs containing obfuscated fonts which will display correctly when sideloaded but will not pass content QA once processed - see [Font Obfuscation] (https://github.com/kobolabs/epub-spec/blob/master/README.md#obfuscated-fonts-are-not-currently-supported-by-the-kobo-cms).
Here’s how to sideload content on Kobo's reading platforms:
eInk
- Connect the device to your computer via USB.
- Find the drive on your computer in Finder or Windows Explorer.
- Drag your ePub onto the device. To trigger the Kobo WebKit, change the file extension to “.kepub.epub”. To trigger the Kobo Webkit for a Fixed Layout title, change the extension to “.fxl.kepub.epub”. (If the extension is left unchanged it will render using the Adobe Digital Editions Webkit.)
- Disconnect your device. The file will automatically appear in your library.
Desktop
- Open the Kobo Desktop app.
- Make sure you have Adobe Digital Editions installed.
- Select the Library tab in Kobo Desktop and press CTRL+Shift+S on Windows or ⌘+SHIFT+S on a Mac. This will display any files in the “My Digital Editions” folder on your computer with the extension .kepub.epub or .fxl.kepub.epub
Android
- Connect the device to your computer via USB.
- Find the drive on your computer in Windows Explorer. If you use a Mac, install and connect to the device using Android File Transfer.
- Drag your ePub onto the device.
- If you use a Kobo Arc, navigate to the Books Collection. Otherwise, navigate to the Kobo App, then tap the side bar menu icon on the top left (the icon with the three horizontal bars vertically stacked) to bring out the sidebar. Then tap on either 'All' or 'All Items' based on your app version.
- Select options (the three dots on the top right) then “Import”.
- Once the files appear, confirm that you want to import them. They will display in your library.
iOS
- Connect the device to your computer with the iOS cable.
- Open iTunes and navigate to iPad -> Apps.
- Select the Kobo app from the box on the left.
- Drag the ePub to the box in the bottom right of your iTunes window. The file will then automatically import and display in your library.
(The Kobo iOS app is registered among apps that open ePub and pdf files. Users can use the standard “open in…” menu from Safari, Dropbox, or any other app that supports it to view their files.)
Windows 8
- Open the Kobo app, navigate to the Library and swipe up from the bottom of the screen.
- Select “import”.
- Select the files on the device that you want to import. (The Kobo app will scan all the files on your device that it can import. You may not be able to transfer files via USB depending on the specific Windows 8 device and may need to transfer them by OneDrive, Dropbox, email or some other method instead.)
- Select “Open” and wait for the files to load into your library.
(Sideloading is not yet supported on the Kobo app for Windows 8 phones.)
ePubs loaded to the Kobo store are protected by Kobo DRM. Kobo can turn the DRM off at the publisher-level, when publishers make a request to the Publisher Operations team.
Kobo’s DRM system hosts content on its reading platforms using advanced security methods, including the use of encryption and hash algorithms. Various keys are used to encrypt content before it is sent to the reading platform. There are unique keys for each eBook, user and device.
At a minimum, Kobo employs encryption standards in the 128-bit version of the Advanced Encryption Standard (AES) of the US Government.
Kobo reading platforms support the core image types outlined in the IDPF spec. This includes JPG, PNG and GIF but not Scalable Vector Graphics (SVG), which are not supported on all reading platforms. (See the Support Grid.) PNG files are preferred over JPG.
All images should use the RGB color model, and not CMYK. Encapsulated PostScript (EPS) images are not supported on Kobo.
The advised maximum size for all image types is 5 MB. ePubs with larger images are still accepted and those images will not cause Kobo apps and devices to crash. However, ePubs with images all under this limit perform optimally across platforms.
Image dimensions should be set in percentages instead of pixels in the CSS for reflowable content. Images with dimensions set by pixels may stretch depending on the orientation, device and user settings. Kobo reading platforms insert max-width and max-height CSS for images and videos to ensures that they are not split over multiple screens.
For a full screen image view on the Android and iOS platforms, users can long press images in reflowable ePubs. Once in full-screen view, users will be able to pinch and zoom. This can also be acheived on eInk devices (running version 3.14 or later) by double tapping images.
If an external cover image is uploaded to both the Kobo system and the ePub, that external image displays as the thumbnail image in the store and in user’s libraries. The internal ePub cover still displays when the user opens the file on their device.
GIF files are not supported for covers.
The suggested optimal ratio for covers on Kobo is 3:4 width:height. (The average size and dimensions for ebook covers in the Kobo store are 800:1224px width:height.) However covers in all dimensions will be rendered consistently across platforms. Content creators are advised to keep their cover images under 3MB. Larger covers will still render but will not improve the display of their content.
Covers should also be listed in the OPF metadata section. The metadata indicates the cover by pointing to the ID of the cover file in the manifest. Kobo uses this tag to identify which image to display as a thumbnail within user's libraries across platforms.
Ex. OPF metadata:
<meta name=“cover” content=“cover-image”/>
Manifest item listing:
<item href="cover.jpg" id="cover-image" media-type="image/jpeg"/>
SVG is partially supported across Kobo platforms. Thorough testing is advised for ePubs with SVG, particularly for text rendering. Content creators are advised to use manifest fallbacks for SVG whenever possible. Refer to the support grid in this document or the test results for Kobo's reading platforms at [ePubtest.org] (http://www.epubtest.org).
For ePub 2.0.1, Kobo reading platforms populate the ToC menu in the book with the ToC from the file toc.ncx (which is in navMap). However, if the toc.ncx is not present, the TOC menu is populated by the Spine listing in the OPF.
When an OPF-spine item is not listed in the TOC.ncx, the Kobo CMS will create a listing for it using the filename or the opening words from the section. This listing will be displayed to the user in the TOC Menu across all reading platforms. This process may be removed in a future release. ePubs that use a nav.html TOC will not be impacted.
For ePub 3.0, Kobo platforms will read the ToC from the ToC table in the nav.html file. When a ToC table is not present, the next available table will be used. If the nav.html is not present, it will populate the ToC with the toc.ncx. If the toc.ncx is not present, it will populate the ToC with the spine listing in the OPF.
The hidden attribute can be used to prevent the ToC listing from appearing in the ePub body while still displaying in the ToC menu. ToC menus on Kobo platforms support nesting up to three elements deep.
Kobo does not require a specific naming convention for the .ncx or .html/.xhtml file, the content creator can name the file as they choose ([filename].ncx, [filename].html). Please note the file naming suggestions provided in the [OPF] (#OPF) section.
The Kobo CMS reads the external metadata provided by the publisher. So most fields in the metadata section of the OPF file are not read. The one exception is the dc:identifier. It should contain the eBook ISBN, also supplied in the external metadata. However, if this field does not contain the eBook ISBN, it must be in the ePub file name. Content creators are also advised that the dc:identifier in the OPF should be identical to the identifier in the .ncx file.
Kobo uses external metadata files to populate the various metadata fields on the Kobo website. The ISBN in the <dc: identifier> field in the OPF file matches the ePub to the external metadata entry. If there is no ISBN in the <dc: identifier> tab, Kobo looks for the ISBN in the ePub filename. The ISBN from the external metadata must match either the <dc: identifier> field or the ePub file name.
The OPF file can be named however the content creator chooses ([filename].opf), but please note the file naming conventions suggested below.
Content creators are advised to use tags for manifest items, specifically the cover tag. Some of these are read across Kobo’s reading platforms and future developments will be able to take advantage of properly tagged items.
Special characters and spaces should not be used for file names within an ePub. This can result in naming inconsistencies with the items listed in the OPF manifest. File names containing non-alphanumeric characters are not fully supported, and their use may lead to undefined behaviour, which may be inconsistent across clients.
Background Colors
Kobo recommends that publishers avoid specifying white as a background colour in the CSS for their ePubs. This can cause text to become unreadable in Night Mode on the Kobo Android app as the text and the background will both display as white. This recommendation only applies to reflowable content as Night Mode cannot be turned on while reading Fixed Layout content.
.c5 { background: #fff }
Small Caps
In order to structure Small Caps that will display correctly on Kobo's reading platforms content creators must use the CSS property "font-variant".
Ex.
p.sc { font-variant: small-caps; }
The property "font-size" is often used incorrectly to format Small Caps and can result in disproportionate text sizing depending on the app/device being used and the font settings chosen by the user. The impact is particularly noticeable when the value used for this property is set to "x-small" or "small". Content creators are also advised to use a font that contains Small Caps glyphs for optimal rendering.
Inline Styling
Kobo strongly advises against the use of inline styling for all content types (reflowable and Fixed Layout). Inline style elements may not be rendered as intended across Kobo's reading platforms. Styling elements should be contained within CSS.
For example, text should be formatted as follows:
HTML:
<p class="text">Sample text.</p>
<p class="text">Sample text, part two.</p>
CSS:
p.text {
margin: 0;
text-size: 10px;
}
Not like this:
HTML:
<p style="margin: 0;text-size: 10px;">Sample text.</p>
<p style="margin: 0;text-size: 10px;">Sample text, part two.</p>
Viewport Height (vh)
Kobo advises against using the CSS element 'vh' in reflowable content as it is not supported on all display engines and may result in text getting cut off or overlapping with other content. More conventional elements such as 'height' or 'max-height' are recommended.
Styling div tags
Kobo advises against applying stlye elements in CSS to 'div' tags. These style elements will be applied to all content wrapped in 'div' tags throughout the ePub. In addition Kobo inserts 'div' tags during processing to enable user functionality (ex. text highlighting) and as a result any content contained within the added tags will inherit the styling applied in the CSS.
ex.
div {
font-weight: bold;
}
TTF, OTF, and WOFF fonts are supported by all of our platforms with the exception of Windows 8. For a detailed breakdown of our font support by platform, check EPUBTEST.org.
Font customization options available to Kobo users on each reading platform:
Android: Droid Sans Serif, Droid Serif.
Desktop: A-OTF Gothic MB101 Pr6N R, A-OTF Ryumin PR6N R-KL, Arial, Ariel Narrow, Arial Unicode MS, Calibri, Calibri Light, Cambria, Cambria Math, Constantia, DFKai-SB, Georgia, KaiTi, Lucida Sans, Palatino Linotype, Meiryo, Meiryo UI, MS Gothic, MS Mincho, MS PGothic, MS PMincho, SimHei, Times New Roman, Tahoma, Trebuchet MS.
eInk: Amasis, Avenir Next, Caecilia, Georgia, Gill Sans, Kobo Nickel, Malabar, Gothic, Ryumin, Dyslexie, OpenDyslexic (the last two are optimized for readers with dyslexia).
iOS: Avenir, Baskerville, Cochin, Georgia, Helvetica, Optima, Palatino, Trebuchet, Verdana.
Windows 8: Cambria, Calibri, Georgia, SegoeUI, Times New Roman, Trebuchet MS, Verdana.
Non-sideloaded titles with obfuscated fonts will display the reading platform’s default font instead of the intended font. As a result all Fixed Layout titles with obfuscated fonts are likely to fail QA. However, work is underway at Kobo to support obfuscated fonts and render these titles correctly. DRM is applied to all ePubs sold through Kobo unless the account/publisher sending the content elects to have Kobo distribute their ePubs without DRM. As a result Kobo users will not be able to extract fonts from ePubs with DRM even when the embedded fonts are not obfuscated.
When opening a new book, the font that displays is the one chosen by the user for their previous open book. For an embedded font, users can select “Document Default” or “Publisher Default” from the font options. The exception is FXL content for which users cannot choose their font. Fonts in FXL content are determined by the CSS in the ePub.
If the reading experience of a book requires that the embedded font be used, consider adding a note to the front matter. Instruct the user to select the “Document Default” font option.
To avoid text-positioning errors, seriously consider embedding and specifying fonts in the CSS for all Fixed Layout ePubs. If fonts are not embedded and specified, the reading platform defaults to Times. Fixed Layout files that use the default font should be tested extensively on Kobo’s reading platforms.
Content creators are advised against referencing fonts in the CSS that are not embedded in the ePub. Kobo devices and devices that Kobo apps can be installed on will have specific fonts included. However the available fonts vary across these devices and there is no way to ensure that any one font will be available on the device chosen by the user. As a result the font styling in the CSS will not display as intended across multiple devices and platforms.
When a user selects an available default font, Kobo reading platforms may not correctly render all glyphs within the script. So Content containing glyphs not present in Kobo’s default apps should be tested across platforms. Creators may want to embed a font that contains the glyphs used in their content to ensure it renders correctly.
Some glyphs do not render on most fonts. In cases where creators are unable to supply embedded fonts they can insert a note into the front matter of their content instructing users to select the font Georgia. It correctly renders the greatest set of scripts.
Kobo is currently working to add built-in fonts to the eInk and Android-reading platforms and render glyphs from all scripts correctly. The Desktop, iOS and Windows 8 platforms already contain built-in fonts that will render glyphs from all scripts.
###Right to Left Page and Text Direction
Kobo has support for right-to-left language formatting in the following areas:
- Kobo supports the writing-mode CSS3 property and associated elements for vertical text layouts (LTR or RTL)
- Kobo supports the HTML5 dir attribute
- Kobo supports ruby text*
-
- Kobo supports the OPF spine-level page-progression-direction attribute for right-to-left page flow ex.
<spine toc="ncx" page-progression-direction="rtl">
<itemref idref="chapter1" />
<itemref idref="chapter2" />
<itemref idref="chapter3" />
</spine>
The "page-progression-direction" attribute was introduced as part of the ePub3 specification. However it can be used in both ePub2 and ePub3 files for Kobo and will pass through processing and display correctly on Kobo's reading platforms in spite of flags that ePub2 files will generate in ePubCheck.
- Kobo supports the OPF spine-level page-progression-direction attribute for right-to-left page flow ex.
*This support excludes the Windows 8 platform.
Footnotes and endnotes on the eInk (with the exception of the original Kobo reader and the Kobo Wi-Fi) and iOS platforms will display as a pop-up box containing the content being linked to. The pop-up boxes also contain links to the HTML sections containing the reference material. On iOS the footnote pop-up will render more than just plain text, including images, links and other content in the footnote or endnote. On the Desktop, Android and Windows 8 platforms users will not see a pop-up but can simply follow the link to HTML section with the reference text.
It is strongly recommended that reference notes use the appropriate ePub:type identifying attribute for footnotes and endnotes. This attribute is currently supported on Kobo's iOS platform and its use is the best way to ensure that footnotes and endnotes will display as intended on iOS as well as future releases on other platforms. All links using the footnote or endnote attribute will display within a pop-up on Kobo's iOS platform. Ex.
<span id="fn0005fn" epub:type="footnote">Text linking to footnote or endnote.</span>
Hyperlinked content not using the epub:type attribute footnote or endnote will display as a pop-up on Kobo's iOS and eInk platforms in cases where the following criteria are met.
-
The link references a location in the ePub and also references a specific node within the HTML. Ex.
<a href=“chapter.html#uniqueID”>link text</a>
Where chapter.html is a file within this epub and where uniqueID is the id of a node within that html document. -
The content in the node is nine charcters or more once stripped of the HTML tags. Ex.
<p id="uniqueID">123456789</p>
Kobo supports the official ePub3 FXL spec. This includes such features as Right-to-Left Reading, SMIL/Read Along, and various rendition-spread options. The rendition:layout property in the OPF determines the layout of the content and is read by all of Kobo’s platforms.
Kobo platforms also read the field true/false to identify whether ePubs should be rendered as FXL. The file containing this field is usually titled com.kobobooks.display-options.xml and can be found in the META-INF directory of the ePub. This file is not required for ePub3 FXL content.
All five values in the rendition:spread property are on the Android, Desktop and eInk reading platforms. The iOS platform supports the properties "Both", "None" and "Auto" but not "Portrait" or "Landscape". The Windows 8 platform supports the properties "None" and "Auto" but not "Both", "Portrait" or "Landscape". Rendition-spread properties are only read at the book level for all reading platforms. Future versions of Kobo’s reading platforms may read the rendition:spread and rendition:layout properties at the spine level.
Pinch and zoom gestures are available on the Android, iOS, and Windows 8 reading platforms. The zoom option is available in the reading menu of eInk devices. The Kobo Desktop App supports three zoom options: Zoom Slider, Double-click to zoom and Scroll to zoom. The zoom slider is incorporated into the navigation bar so that users can adjust it to zoom in and out. Alternatively, users can to zoom in by double-clicking anywhere on the page or adjust the zoom by scrolling up and down with a mouse while holding down the Ctrl (PC) or Command (Mac) key.
Kobo strongly advises against the following when formatting Fixed Layout content:
-
Text boxes with inline styling. This may result in inconsistent rendering across platforms, resulting in text overlap or incorrect positioning.
-
The use of images where the width or height (in pixels) exceed the dimensions of the viewport. ePubs containing images that exceed the viewport dimensions may not render correctly on the eInk platform.
-
The use of negative positioning when placing text, images or other content in CSS. Ex.
.li
{ text-align: justify;
padding: 0;
margin: 0;
word-spacing: -15px;
}
Kobo Advises Against Overuse of Fixed Layout
Content creators are advised against producing Fixed Layout ePubs solely for the purpose of reproducing a print layout. Text cannot be resized by users while reading Fixed Layout content and as a result small text can only be read by zooming in. This can greatly diminish the reading experience particularly on eInk devices, smartphones and Desktop applications. Fixed Layout serves comics, children's books and other categories well but is not an ideal format for text heavy content that could be displayed as reflowable content. Furthermore Fixed Layout ePubs require more in depth testing prior to distribution to ensure that they display correctly across multiple reading platforms.
SMIL (Synchronized Multimedia Integration Language) is supported for FXL titles on Android and iOS. Audio files must be encoded using Apple iTunes AAC-LC mp4-v2 codec, 256 kbps.
Note: the Kobo Android platform does not currently support:
- Non-Linear playback
- Text highlighting for SVG text
When the rendition:spread property is set to “none” or “auto”, Android displays a full spread in FXL Read Along content in landscape.
Custom text colors for highlighting are not currently supported on Android. However, custom text colors for highlighting is possible on iOS. The iOS app uses the CSS class ‘kobo-smil-highlight’ to color highlighted text. So, by adding that class to the CSS plus a color declaration, the color of the highlighted text on the app can be customized.
SMIL for reflowable content is supported on iOS but is not supported on the Android, Desktop or Windows platforms.
The Kobo Android and iOS platforms will render FXL ePubs that meet certain criteria with an image-based Fixed Layout reader. This reader features significantly faster panning, zooming, and page-turns than the standard one. Designed to enhance the reading experience of comics, it works for any FXL ePubs composed entirely of images.
ePubs that meet the following criteria will be displayed with the image-based reader on Kobo’s iOS and Android platforms:
- The content is Fixed Layout.
- The ePub does not contain SMIL content.
- An image must be available for each spine item. Spine items are inspected for images using these rules — and each spine item must contain one of the following formats:
- a. either a non-SVG image (e.g. PNG)
- b. or an SVG image with a non-SVG image fallback provided in the manifest. In this case, the fallback image is used in the comics renderer
- c. or an HTML file which falls under one of the following categories:
- i. either it contains a single ‘img’ tag which references an image. In this case, this image will be used
- ii. or it contains a svg definition with an ‘image’ child tag referencing an image. In this case, the referenced image will be used. NB: embedded object tags (‘object’), which may include an SVG image in the ‘data’ attribute, do not fall into this category
- iii. or an HTML page which contains no child elements under ‘body’. This item will be rendered as a blank white page.
For example, a file that lists spine items, manifest items, and contains nothing but an image in the HTML body will trigger the image-based renderer.
First spine item:
<spine page-progression-direction="ltr" toc="ncx">
<itemref idref="page0-xhtml" linear="yes"/>
Matching item in manifest:
<item id="page0-xhtml" href="contents/Page00.xhtml" media-type="application/xhtml+xml"/>
HTML body for item:
<body>
<div id="layer0">
<image width="1076" height="1394" xlink:href="../images/Image01-1-0.jpg"/>
</div>
</body>
If images are set using the background property of elements the platform will fall back to using the default reader.
On Android, if the image is determined to be twice as large as the screen in any dimension, a low-res version of the image loads when the user turns a page. Within a second, the high-res version replaces the original image. This optimization prevents memory issues when users quickly flip through pages. The low-res image might appear slightly blurry or soft compared to the final hi-res image.
Testing across platforms for ePubs with multimedia and other media overlays is recommended.
Embedded audio and video is currently supported on Kobo’s iOS and Android platforms for all content.
Windows 8 does not currently support embedded audio and video. Kobo eInk devices and the desktop app do not support embedded audio and video either but will display any content included as a fallback using the switch element display instead.
Autoplay Functionality is not currently supported
Kobo's platforms do not currently support autoplay functionality for embedded media. Elements using this tag will display but will not begin playback without user interaction.
Ex.
<audio class="myaudio" src="sounds/audio.mp3" autoplay="autoplay">Sample text.</audio>
Kobo’s Android and iOS platforms support JavaScript for Fixed Layout and reflowable ePubs, but it is recommended not to use JavaScript in reflowable content in ways that may alter the layout of the book. Kobo’s eInk and Desktop platforms have limited support for JavaScript, and do not support interactive JavaScript elements. ePubs with JavaScript should contain fallback statements. This way, platforms that do not support JavaScript can still produce a coherent reading experience. Thorough testing on all platforms is strongly recommended to ensure that fallback as well as JavaScript content renders correctly.
Disabling Menu Activation for Interactive Elements
Taps in book content (on elements other than links) are passed up to the Kobo reading apps in order to trigger menus and other reading system interactions. To avoid having your interactive elements trigger unrelated reading system functionality JavaScript files must contain event listeners for both click and touchend (or touchstart) events, and both listener functions must call preventDefault() on both click and touchend (or touchstart, if you’d prefer) events. Any interactive logic will need to be implemented in the touch handler, rather than the click handler, as in the example below:
exampleElement.addEventListener('click', handleClick, false);
exampleElement.addEventListener('touchend', handleTouch, false);
function handleClick(event) {
event.preventDefault();
}
function handleTouch(event) {
exampleElement.style.background="red";
event.preventDefault();
}
Please note that MathML is not presently supported on the Kobo Android or Windows 8 platforms. At present content creators are encouraged to either include a note to indicate that the content is not optimized for Android and Windows 8 devices, or else use images (rather than MathML) for the mathematical content.
Any items listed in the manifest that are not standard ePub Content Documents should be accompanied by fallback items. Extensive testing should be done across platforms whenever including non-core items in an ePub. More on the IDPF specification on manifest fallbacks can be found here.
Ex.
<manifest>
<item id="xpgt1" href="styling/noncorestyling.xpgt" media-type="application/vnd.adobe-page-template+xml" fallback="css"/>
<item id="css" href="styling/content.css" media-type="text/css"/>
</manifest>
When embedding audio and video Kobo recommends using intrinsic fallbacks so that users reading on platforms that do not support embedded media (ex. eInk) can be directed to other platforms if they wish to access the content. More on IDPF specification on intrinsic fallbacks can be found here.
Ex.
<audio controls="">
<source src="embeddedaudio.mp4">
<p>The device you are reading on cannot play audio content but you can access the media in this book by opening it on your phone or tablet.</p>
</audio>
Publishers can set the amount of content they make available in previews. They use their metadata feed or work with Kobo’s Publisher Operations team to customize their account settings.
On the account level, previews are set to display 5% of the ePub’s content by default. Previews can be turned on or off. The maximum percentage that accounts can be set to is 25%.
On the product level, the default is 5%. Publishers can set preview percentages for individual titles. They can use the Kobo Excel metadata template or ONIX 3.0 with the tags EpubUsageType, EpubUsageStatus or EpubUsageLimit. Previews can be set between 0% and 25%.
Publishers can also upload custom previews by using the naming convention ISBN_preview.epub in the preview files they distribute.
Sometimes tables wider than four columns may not be readable in reflowable ePub files, particularly on eInk devices. Content producers adding tables with more than four columns are advised to test their content on all Kobo reading platforms. Likewise, when HTML tables do not render as intended, they can reformat or capture the tables as high-resolution images.
Kobo recommends the following limits for ePub and ePub component sizes. Files exceeding these limits should still to load to the Kobo store and be accessible on all reading platforms but will take longer to download to users’ devices and will take up more memory. To ensure optimal performance content creators are advised against producing files that exceed these limits.
- 5 MB/image in FXL and Reflowable ePubs
- 10 MB of embedded content/each HTML file in an ePub
- 3 800 000 pixels/viewport or ~1950x1950 in FXL ePubs
- 1 GB/ePub
The following table lists features supported by at least one Kobo platform but not uniformly supported across all platforms. Features not listed here are either supported across all platforms or not supported on any platforms.
| Platform | MathML | SMIL | JavaScript | CSS Animations | Audio/Video |
|---|---|---|---|---|---|
| Android | N | Y | Y | Y | Y |
| Desktop | Y | N | N | Y | N |
| eInk | Y | N | N | Y | N |
| iOS | Y | Y | Y | Y | Y |
| Windows 8 | N | N | N | N | N |
Learn more about Kobo’s ePub support at epubtest.org. It’s categorized into required and optional features.
If you encounter any rendering issues you can bring them to our attention at [email protected]. Please provide as much detail as possible, including app version, device, and screenshots if possible. Any comments or concerns about the documentation above can be submitted directly via Github comments. Immediate responses to all emails and comments cannot be guaranteed but all feedback related to documentation and content rendering is appreciated.
If you are already configured as a publisher or distributor with Kobo and have a questions concerning content management (metadata or ePub uploads, pricing, pre-orders, etc.) you can follow up with your contact on the Publisher Operations team.
If you are a small publisher or a self-published author and would like to sell your content through Kobo you can do so through Kobo Writing Life.