This package is a starter-kit for a simple EPUB3-eBook, supporting text, images, audios and videos as content. The folder-structure is inspired by the suggested structure offered by SIGIL.
It uses XHTML and CSS, no Javascript.
EBooks in EPUB3-format are - simply spoken - archives (like ZIP-files). You can extract an EPUB-file like any other archive.
The content of eBooks is written in XHTML-files. EBooks have a lot in common with HTML-websites.
If you are not familiar with (X)HTML, please visit W3C to get the differences:
If you are not familiar with SASS please read some basic information about the SASS-concept as a preprocessor for css-files. Please visit
If you are using VSCode we recommend to install the extensions XML-tools and LiveSassCompiler. The sass-compiler-extension makes the maintenance of your css easy.
This repository reached End Of Life on July 31, 2026. The entire project is no longer maintained and the repository is read-only. You can still fork it if it can be useful to you.
Licence
This repository is released under MIT Licence © 2026, Uwe Fissenebert.
There are many ways to generate EPUB-books. You can use different editors and tools to generate a book from scratch or from existing files. Here are some tipps to do the job:
- Keep things simple. Not all eBook-readers support all eBook-features.
- Define YOUR (internal) folder-structure for the eBook. Default folder-structures and -names or default filenames provided by the editors may not fit your needs.
- Define a folder-structure for your development-environment. It is a good idea to keep the sources (text, images, graphics, videos etc.), that are ment to be used in the eBook separated from the eBook itself. This gives you a fallback-option.
Some scss-files make use of the content of other scss-files. So be careful if you rename or remove a scss-file. It is useful to understand the principles of SASS and SASS-variables to get most out of this repository-
- Copy sources you want to use first to the (re)sources-folder-structure of your project. Import the (edited) sources from these folders into your eBook.
- Define a file-name-structure to keep things organized (inside and outside of the eBook). This is very important when an eBook gets a bit more complex.
- Try to work with versioning and fallbacks. BACKUP, BACKUP, BACKUP!
- Define a fixed workflow (to sources, to content, testing, validating).
- Pay attention to rules and best-practice-examples you can find online.
- PAY ATTENTION TO ACCESSIBILITY!!
We strongly recommend to keep yourself organized when writing an eBook. If you do not start from scratch ie. converting a file from a wordprocessor to an EPUB-file, you may pay attention to some aspects (see below).
There are plugins out there that convert files from wordprocessors (like MS WORD or LibreOffice) to an EPUB-structure. Please keep in mind that this can only be a starting point to get BASIC conversions done. When we started an eBook this way we found out, that the result never validated W3C, DAISY or epubChecker out of the box. We still had to do a lot of work to get a valid eBook.
Please read about our experiences below.
The template is a common eBook in EPUB3-format. You can open it in any EPUB-editor or -reader.
If you are using VSCode, generate a new personal repository from this repository.
If you use a different editor (like ie. Calibre), download this repository as a ZIP-file, unpack it.
The eBook itself is located inside this repository-folder:
src/final/epubGeneric.epub
There are various ways to use this repository. You can just add the provided stylesheets to your eBook-project or build/modify them with the SASS framework. All needed scss-files are included in this repository.
The stylesheets-structure was built to support the default SIGIL-css-files-location.
You can either link generic.css and local.css or an alternative stylesheet in your EPUB-XHTML-file. Please do not forget to import the entire (modified) css-files in SIGIL, too.
The css-files are commented. There is a minimized version of each css-file available as well.
A major aspect of the template is accessibility. So the template does not use all the fancy features that modern EPUB3-files may offer. The W3C-rules and best-practice-examples for accessibility (DAISY) inspired this template.
We tested the accessibility with the ACE by DAISY-tool
Get ACE-tools here:
There is an archive-file daisy-ace-test with the ace-test-results in the folder res/test/daisy
Please pay always attention to accessibility (DAISY).
EPUBCheck evaluates EPUB publications against the official EPUB specifications.
Get EPUBCheck here:
The provided CSS-files created by SASS passed all W3C-CSS-level3 tests:
The files with the final test-results before publishing this repository are located inside the repository here:
res/test
Is this project still active?
No. There is no maintenance. Please use it as it is as a starting-point for your own EPUB3-project.
There is no Javascript-support. It's pure XHTML and CSS.
This repository was built to get a default template for EPUB3-books. When we create a new EPUB3-book we fork this repository to a new one and import the new one in VSCode.
We use SIGIL as our main EPUB3-editor and VSCode as our external editor. VSCode offers some extra benefits to make major changes to the XHTML-files than SIGIL does.
Get SIGIL here:
We use SIGIL under LMDE (Linux Mint Debian Edition). SIGIL for Windows, MacOS and Linux may have functional differences. Check your Python-version if you want to use SIGIL-Plugins under Linux.
Inside SIGIL-preferences we set VSCode as the external editor. We use this editor for the major editing work.
The folder-structure of epubGeneric.epub is inspired by the default folder-structure provided by SIGIL. We made some changes to this default-structure to support our needs. All css-files are located inside SIGIL in the folder /STYLES.
We do not use the default SIGIL-css-files. This repository supports SASS for creating the custom css-files we use in our projects. The editing of the SASS-files is done by VSCode and the extension LiveSassCompiler. We import the output-css-files into the SIGIL-editor.
There are three major folders:
- res
- sass
- src
This folder keeps the source-files (resources) that were used to generate the eBook. There are SVG-files we used to generate the cover-image and posters (video).
You find a set of predefined dummy-image-templates (SVG-format) of different sizes (folder res/media/graphics). These dummy-files may help you to style your content.
These SASS-subfolders define the css-rules for the final css-output
- abstracts (functions, mixins and variables)
- base (basic css, colors, fonts, media, typography)
- contentindex (book-index)
- layout (components, content, footer, header, navigation)
- locals (all css for the local.css-file)
- navigation (toc = formatting navigation in the table-of-contents)
- toc (styling the toc itself)
If you use the LiveSassCompiler-plugin in VSCode, there is a sample of a config-snippet for this extension to put into the settings.json of VSCode (folder res/misc). Please change the output-folders to your need.
The SASS-structure generates two basic css-files:
- generic.css
- local.css
In addition you get three more css-file
- sgc-index.css (for the index-section of the book)
- sgc-nav.css (styling of the toc-navigation)
- sgc-toc.css (the styling of the toc itself)
These three css-files are generated by SIGIL automatically with default-rules if they are missing in the Styles-folder. With these three files you can fully control the aappearence of the index, nav, toc and toc-navigation.
Our settings for the LiveSassCompiler-extension sets the output-folder of these files to src/Styles, but you can change this easily in the VSCode settings.json.
The generic.css defines all basic rules for the book. Please load it at the first place in a XHTML-file.
The local.css may add or modify css-rules. We have sometimes the need for css-rules only necessary for a special project (book). We put these rules in the local.css-file and leave the generic.css untouched. Please load local.css after generic.css in a XHTML-file.
The css-notation follows the BEM-name-conventions: Block Element Modifier.
Encapsulates a standalone entity that is meaningful on its own. While blocks can be nested and interact with each other, semantically they remain equal; there is no precedence or hierarchy. Holistic entities without DOM representation (such as controllers or models) can be blocks as well.
Parts of a block and have no standalone meaning. Any element is semantically tied to its block.
Flags on blocks or elements. Use them to change appearance, behavior or state.
- .title__description
- .img__figure--right
- .audio__title--label
- .video__landscape
- .bg__color--grayscale-lighter
- .fg__color--lightest
The sass-folder has subfolders. The subfolders organize the css-creation-process. Each subfolder has a file _index.scss. If you are not familiar with sass-import by _index-files, please read some sass-documentations about this sass-feature.
This is the folder for the eBook-sources. The subfolders have the same name as the internal book-folders we defined in SIGIL. In our workflow we put all resources ready to be used in SIGIL in the entire subfolders of /src. Whatever file lives in these subfolders is ready for the eBook.
All subfolders that have a corresponding folder inside the eBook start with a capital letter.
SASS outputs the css-files to the folder src/Styles. When you have made changes to the css in any sass-file and created a new version of your css-files, please delete the previous version of a css-file in SIGIL from the SIGIL-folder Styles. Then import the new css-file from src/Styles into SIGIL and save the eBook. This updates the eBook with the new css-rules.
Inside of this folder lives a single image. Use this image when you create a cover-page inside SIGIL.
The template uses a custom font: Roboto.
This folder contains the ttf-files to generate the font-face-rules by SASS. Please have a look at the file sass/base/_font-face.scss. This sass-file includes the ttf-files and generates the @font-face rules.
The fonts-files must be present in the eBook itself. Otherwiese a reader may not be able to display the font defined in the css. Please keep in mind that not all readers support custom fonts.
This folder contains SVG-files you can use to create your own cover- or poster-files.
This folder contains the latest version of the epubGeneric.epub book. Please import this file into your editor or reader.
There is a navigation-file, but no NCX-file, because this template is ment for EPUB3 and does not support EBUB2. If you also want to support the EPUB2-format you can add a NCX-file in SIGIL easily.
KEEP ORGANIZED.
BACKUP, BACKUP, BACKUP!
We defined a naming-structure for the files of an eBook. An eBook has three major sections:
- frontmatter
Preliminary material to the main content of a publication, such as tables of contents, dedications, etc. - bodymatter
The main content of a publication. - backmatter
Ancillary material occurring after the main content of a publication, such as indices, appendices, etc.
Every eBook-reader supports this structure to display an eBook properly. A valid eBook respects these three attributes for a XHTML-body- or section-tag.
Examples:
<body epub:type="frontmatter">
<section epub:type="bodymatter">
We use this XHTML-filenaming for the book-content:
BOOK-SECTION_PART_subpart.xhtml
Examples
- frontmatter
FR_TITLE_title.xhtml
FR_FOREWORD_foreword.xhtml - bodymatter
BO_PROLOGE_prologe.xhtml
BO_COLORS_colors.xhtml
BO_COLORS_grayscale.xhtml
BO_COLORS_primary.xhtml - backmatter
BA_AUTHOR_author.xhtml
BA_LOI_list_images.xhtml
BA_LOI_list_illustrations.xhtml
BA_LOA_audios.xhtml
BA_LOV_videos.xhtml
This helps us to keep the overview of the book-structure (order of content) and makes it easy to drag/drop content-files to a different position. The table-of-contents (toc) respects the file-position within the book-structure.
Feel free to create your own naming-syntax for content-files.
We try to keep the content of a XHXTML-file as short as possible. It is better to create some smaller sub-files with portions of the content instead of putting all content in a single large XHTML-file. Our naming-conventions help us to keep track of the book-structure.
We split parts with a lot of content in smaller chapter-files and if needed chapters in sub-chapter-files and organize them by the XHTML-filenaming and positioning inside the eBook-structure. This keeps things organized and maintainable.
We initialize a new page in SIGIL. But most of the work is done with VSCode. We have defined a lot of code-snippets for the content. The snippets include placeholders for all the classes, attributes, roles etc. we need to create valid content-elements.
The content for a content-element (section, p, img, etc.) can be inserted by a code-snippet. We encourage you to build your own snippets-library.
There are plugins out there that convert files from wordprocessors to an EPUB-structure. We take such files as a resource and put them in the res-folder first. We copy all graphics, images, audios and videos used in the source-file to the entire subfolder of the res-folder.
We found out, that epub-types and ARIA-roles and -attributes are often not present in a converted file. That means, using a converted file directly as the eBook-content increases the amount of manual work to get valid content. We get better off by copying content from the resources (converted files) to our (valid) code-snippets, that have placeholders for roles, attributes and other stuff.
Sometimes the sources in the res-folder need some editing or renaming first before they can be used in the eBook. Videos ie. need poster-images to show up as a video-cover in the eBook. Image-sizes are often unnecessarily big. You name it.
If we need additional (new) content, we put this in the res-folder(s) first.
The res-folder is our fallback-folder just in case and an important backup-source.
The eBook itself is built by using the resources. We put all content from the resource-file(s) to the entire src-folder. Everything in the src-folders is ready to be used in the eBook.
We build the eBook-content from the files in the subfolders of the src-folder.
When a part of the eBook is finished (beta), we run all tests (W3C, DAISY, epubCheck) on the eBook before we start creating the next part.
We open the final eBook with some readers to check, if the book displays properly.
You may look at this workflow as too complex. Yes, there are shorter ways to create an eBook. But if you have to maintain an eBook (versioning, different publishers) or convert it, this workflow may save you time.