├── LICENSE.md ├── LICENSE.xhtml ├── README.md └── スクリーンショット 2016-02-22 14.51.00.png /LICENSE.md: -------------------------------------------------------------------------------- 1 | [![Creative Commons 2 | License](http://i.creativecommons.org/l/by-nc/4.0/88x31.png)](http://creativecommons.org/licenses/by-nc/4.0/)\ 3 | This work is licensed under a [Creative Commons 4 | Attribution-NonCommercial 4.0 International 5 | License](http://creativecommons.org/licenses/by-nc/4.0/). 6 | -------------------------------------------------------------------------------- /LICENSE.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Creative Commons License 8 | 9 |
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. 10 | 11 | 12 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Kobo EPUB Guidelines 2 | What’s in this Document: 3 | 4 | * Elements of the EPUB spec that Kobo does and does not support. 5 | * Features of the five Kobo reading platforms. 6 | * Recommendations on file production and testing for content creators. 7 | 8 | 9 | ### Table of Contents 10 | 11 | 1. [EPUB Versions Kobo Supports](#epub-versions-kobo-supports) 12 | 2. [Kobo Reading Platforms](#kobo-serves-content-to-users-on-these-5-reading-platforms) 13 | 3. [Kobo Recommends Initial EPUB Check](#kobo-recommends-initial-epub-check) 14 | 4. [Sideloading for Testing Purposes](#sideloading-for-testing-purposes) 15 | 5. [Digital Rights Management (DRM)](#digital-rights-management-drm) 16 | 6. [Image Formatting](#image-formatting) 17 | 7. [Cover Images](#cover-images) 18 | 8. [Scalable Vector Graphics (SVG)](#scalable-vector-graphics-svg) 19 | 9. [Table of Contents (TOC)](#table-of-contents-toc) 20 | 10. [OPF](#opf) 21 | 11. [CSS](#css) 22 | 12. [Supported Fonts](#supported-fonts) 23 | 13. [Obfuscated Fonts](#obfuscated-fonts-are-supported-on-all-reading-platforms) 24 | 14. [Embedded Fonts](#embedded-fonts-can-be-selected-by-users) 25 | 15. [Embedding All Fonts in Fixed Layout](#all-fonts-used-in-fixed-layout-content-must-be-embedded-and-cannot-be-modified) 26 | 16. [Languages](#languages-other-than-english) 27 | 17. [Right to Left Page and Text Direction](#right-to-left-page-and-text-direction) 28 | 18. [Footnotes/Endnotes](#footnotesendnotes-are-fully-supported-across-kobo-platforms) 29 | 19. [Fixed Layout](#fixed-layout-fxl-support) 30 | * [Synthetic Spreads](#synthetic-spreads) 31 | * [SMIL](#kobo-supports-smil) 32 | * [Image-Based FXL Reader](#image-based-fxl-reader) 33 | 20. [Multimedia Support / Media Overlays](#multimedia-support--media-overlays) 34 | 21. [JavaScript Support](#javascript-support) 35 | 22. [MathML](#mathml-support) 36 | 23. [Fallback Statements](#fallback-statements) 37 | 24. [EPUB Previews](#epub-previews) 38 | 25. [Tables](#tables) 39 | 26. [Limitations and Maximums](#limitations-and-maximums) 40 | 27. [Support Grid](#support-grid) 41 | 28. [Common QA Failure Issues](#common-qa-failure-issues) 42 | * [Pixelated or Low Resolution Images](#pixelated-or-low-resolution-images) 43 | * [Missing Images](#missing-images) 44 | * [Text Spacing and Overlap Issues](#text-spacing-and-overlap-issues) 45 | * [Viewport Issues](#viewport-issues) 46 | * [Read-Along issues](#read-along-issues) 47 | * [Audio Video Issues on Android and iOS Platforms](#audio-video-issues-on-android-and-ios-platforms) 48 | * [Two Pages Display in Portrait Orientation on Android](#two-pages-display-in-portrait-orientation-on-android) 49 | 29. [External Resources](#external-resources) 50 | 30. [Questions?](#still-have-questions) 51 | 52 | ### EPUB Versions Kobo Supports 53 | 54 | Kobo supports ePub, the universal open standard eBook format maintained by the W3C EPUB3 Community Group [(W3C)](https://www.w3.org/publishing/epub3/epub-spec.html). The current version is EPUB 3 but Kobo still supports its predecessor, EPUB 2.0.1. 55 | 56 | Any EPUB file sent to Kobo will be made available on all of Kobo's reading platforms. 57 | 58 | *The Kobo Vox and Blackberry apps both run older versions/ports of the Android app and will not be updated. 59 | 60 | **Fixed Layout content display on Sony Readers is dependent 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. 61 | 62 | The EPUB 3.2 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](https://www.w3.org/TR/epub-33/#references) because changes to them could impact file production. 63 | 64 | Kobo supports a subset of elements from the EPUB 3 spec. The following covers which elements are supported across Kobo’s reading platforms. 65 | 66 | **Kobo does not accept** .mobi, KF8, PDF or any format outside of EPUB that may be used to format eBooks. 67 | 68 | ### Kobo Serves Content to Users on These 5 Reading Platforms 69 | 70 | 1. eInk/EPD — Kobo eInk devices (Touch, Mini, Glo, H2O, Aura, Aura Edition 2, Aura H2O, Aura One, Clara HD, Forma) 71 | 2. Desktop — the Kobo desktop app for PC and Apple Computers 72 | 3. Android — all Android devices running the Kobo app including all Kobo Arc versions 73 | 4. iOS — iPad, iPhone and iPod Touch 74 | 5. Windows — all tablets, smartphones and computers running Windows apps. 75 | 76 | ### Kobo Recommends Initial EPUB Check 77 | 78 | The Kobo CMS runs incoming files through [EPUBCheck](https://github.com/w3c/epubcheck) version 4.2.4. If your EPUB raises failure messages that are known to prevent files from loading or displaying correctly you will receive an automated failure report indicating which files failed validation and why within two business days. 79 | 80 | Not all EPUBCheck flags will result in files failing upon ingestion but Kobo strongly recommends that only files that pass EPUBCheck without flags are distributed. EPUBs that raise warning flags may pass ingestion but still fail content QA if they produce display issues on Kobo's reading platforms. 81 | 82 | ### Sideloading for Testing Purposes 83 | 84 | 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 renderingissues@kobo.com and the EPUB in question will be logged for investigation. 85 | 86 | Here’s how to sideload content on Kobo's reading platforms: 87 | 88 | **eInk** 89 | 90 | 1. Connect the device to your computer via USB. 91 | 2. Find the drive on your computer in Finder or Windows Explorer. 92 | 3. 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. This is the default display engine for sideloaded content to enable bookmarking, searching and highlighting.) 93 | 4. Disconnect your device. The file will automatically appear in your library. 94 | 95 | *Sideloaded EPUBs with the ".fxl.kepub.epub" or ".kepub.epub" will disable bookmarking and note keeping. Thumbnails for covers may not display. Otherwise the reading experience and content display will be identical to how the file would display when loaded through the store. Leaving the extension as ".epub" will enable bookmarking and note keeping and will trigger the ADE display engine.* 96 | 97 | 98 | **Desktop** 99 | 100 | 1. Open the Kobo Desktop app. 101 | 2. Make sure you have [Adobe Digital Editions](https://www.adobe.com/ca/products/digital-editions/download.html) installed. If you do not wish to install ADE you can skip this step by creating a folder named "My Digital Editions" in your "My Documents" folder. On a Mac, the folder must be named "Digital Editions" instead. 102 | 3. Select the My Books 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 .epub 103 | 4. Any sideloaded books can be removed from the My Books tab by right clicking on the book and selecting "Remove Download". 104 | 105 | **Android** 106 | 107 | 1. Connect the device to your computer via USB. 108 | 2. Find the drive on your computer in Windows Explorer. If you use a Mac, install and connect to the device using [Android File Transfer](http://www.android.com/filetransfer/). 109 | 3. Drag your EPUB onto the device. 110 | 4. 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. 111 | 5. Select options (the three dots on the top right) then "Import". 112 | 6. Once the files appear, confirm that you want to import them. They will display in your library. 113 | 114 | **iOS** 115 | 116 | 1. Connect the device to your computer with the iOS cable. 117 | 2. Open iTunes and click the device's icon in the upper-left corner of iTunes. 118 | 3. Select File Sharing from the Settings menu on the left. 119 | 4. Select the Kobo Books app from the Apps box in the iTunes window. 120 | 5. Drag the EPUB to the Kobo Books Documents box in the iTunes window. If drag and drop functionality is not working then select the "Add File..." button and select the EPUB you want to add to the app. The file will then automatically import and display in your library. If it does not appear even after refreshing your library, closing the app and opening it again should cause the sideloaded titles to appear. 121 | 122 | (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.) 123 | 124 | ### Digital Rights Management (DRM) 125 | 126 | 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. 127 | 128 | 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. 129 | 130 | At a minimum, Kobo employs encryption standards in the 128-bit version of the Advanced Encryption Standard (AES) of the US Government. 131 | 132 | ### Image Formatting 133 | 134 | Kobo reading platforms support the core image types outlined in the [W3C spec](https://www.w3.org/TR/epub-33/#sec-core-media-types). This includes JPG, PNG, Scalable Vector Graphics (SVG), and WebP. PNG files are preferred over JPG. 135 | 136 | All images should use the RGB color model, and not CMYK. Encapsulated PostScript (EPS) images are not supported on Kobo. 137 | 138 | **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. 139 | 140 | **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. 141 | 142 | **Images should not have transparent backgrounds.** This will result in the reading system inserting a default background color or pattern. Fixed Layout titles with where image backgrounds are transparent will fail QA in cases where the content is unreadable. 143 | 144 | **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 achieved on eInk devices (running version 3.14 or later) by double tapping images. 145 | 146 | 147 | 148 | ### Cover Images 149 | 150 | 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. External cover images must have the ISBN in the filename ex. "9781234567890.jpg" or "9781234567890.png". 151 | 152 | GIF files are not supported for covers. 153 | 154 | 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. 155 | 156 | 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. 157 | 158 | Ex. 159 | OPF metadata: 160 | 161 | `` 162 | 163 | Manifest item listing: 164 | 165 | `` 166 | 167 | **Cover images must be contained in their own XHTML files.** Kobo's eInk devices will activate the Fixed Layout reader for the XHTML file containing the cover image to optimize the display. As a result any text or images that have been placed in the same XHTML file as the cover will be displayed as Fixed Layout content. The user will be unable to resize the text and some of the content may not display on the screen at all. 168 | 169 | It is recommended that cover images be embedded in the html using the `` tag, rather than using the `background-image` CSS property. The CSS `background-image` method is not supported by the automatic cover extraction process. Books that do use the CSS method will require separate covers to be submitted in order for covers to appear in the store and in customer libraries. 170 | 171 | Kobo advises against placing links in covers. This can create a poor reading experience when attempting to page forward and a link is triggered instead. 172 | 173 | ### Scalable Vector Graphics (SVG) 174 | 175 | Text, images and animations in SVG are supported on all Kobo reading platforms (performance on eInk is limited but the animations will function). Placing SVG items directly in the spine (as opposed to in XHTML files in the spine) is partially supported (Android and iOS) but is not recommended. 176 | 177 | **Scaling images may prevent them from displaying on eInk and Desktop.** Some ePubs will rotate and shrink images down to the size of a single pixel and then blow them back up to the intended view size. This will work on Android, iOS and Windows but on Desktop it results in the image either not displaying at all or only displaying as a single pixel. 178 | 179 | Not supported: 180 | ```svg 181 | 182 | 183 | 184 | ``` 185 | 186 | If the content is formatted this way instead it will display correctly on all Kobo platforms (note that the image will still be rotated but not shrunken). 187 | 188 | Supported: 189 | ```svg 190 | 191 | 192 | 193 | ``` 194 | 195 | ### Table of Contents (TOC) 196 | 197 | Kobo does not require a specific naming convention for the NCX (in epub2) or EPUB navigation document (in EPUB3). The content creator can name the file as they choose (i.e. `your_toc_filename.ncx` or `your_toc_filename.xhtml` respectively). However, please note the general file naming suggestions provided in the [OPF](#opf) section. 198 | 199 | #### For epub2 200 | Kobo reading platforms populate the TOC menu using the `navMap` element of the NCX. If the NCX is not present, the TOC menu is populated by the epub's OPF `spine`. 201 | 202 | When an OPF `spine` item is not listed in the NCX, Kobo 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. EPUB3 files, which use the EPUB navigation document, will not be impacted. 203 | 204 | #### For EPUB3 205 | Kobo platforms populate the table of contents with the items listed in the [toc nav element](https://www.w3.org/TR/epub-33/#sec-nav-toc) of the [EPUB navigation document](https://www.w3.org/TR/epub-33/#sec-nav). The `toc nav` element is a `nav` element with an `epub:type` attribute that has been assigned the value `toc`. 206 | 207 | Example: 208 | ``` 209 | 219 | ``` 220 | 221 | **Please note:** For consistency across Kobo platforms, it is highly recommended that all EPUB3 files include the `toc nav` element; fallbacks vary depending on the platform. 222 | 223 | When a `toc nav` element is not present in an EPUB3: 224 | - EPD devices and KDA fall back to listing each filename in the epub's OPF `spine`. 225 | - iOS falls back to the `page-list nav` element. 226 | - If a `page-list nav` is not available either, the TOC will appear blank, but will still function as a list of links to each file listed in the epub's OPF `spine`. 227 | - Android falls back to the next available `nav` element in the order in which they occur: either a `page-list nav` or a `landmarks nav`. 228 | - If neither a `page-list nav` element nor a `landmarks nav` element exists, the TOC will be empty. The OPF `spine` is not used as a fallback on Android. 229 | 230 | **Please note:** If an NCX is included in an EPUB3, it will be ignored. It will not used as a TOC fallback on any Kobo platforms. 231 | 232 | 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 on iOS and Android. Nested TOCs are flattened on EPD and Desktop. 233 | 234 | **Landmarks will display as TOC items but will not trigger behaviour on the apps.** The EPUB specification does not define any specific way reading platforms are supposed to handle landmarks (