gen-epub-book is a loose file to ePub assembly/conversion tool for everyone not afraid of not using Word.
gen-epub-book allows you to assemble ePub e-books using an easy-to-read, easy-to-write plaintext format.
gen-epub-book" is two things:
(1) a plaintext descriptor syntax; and
(2) a software tool, that assembles that descriptor and files referenced thereby into an ePub e-book.
The "design goal" of
gen-epub-book’s descriptor syntax is to make it as consistent and obvious at the first sight as possible.
The idea is that a
gen-epub-book descriptor should be writable by any person with minimal technical knowledge.
This guide is designated for non-programmers. If you're a programmer, see the more in-depth programmer's version.
gen-epub-book is free software, available under the MIT open source license.
See the License heading for more information.
Any topic related to
gen-epub-book – both the descriptor syntax and the software –
is fair game for discussion over at
gen-epub-book's and this webpage's issue trackers
I've also set up a GitHub issue for simple questions and clarifications.
If you don't have a GitHub account, you can shoot me an e-mail .
I hope that these facilities will lead to good ideas for future improvements to
If you're running Ubuntu or Windows, you can simply grab a
gen-epub-book.rs executable from the releases page.
Those executables should work when ran from anywhere and without any external dependencies.
gen-epub-book's descriptor syntax is line-based – each line in the file specifies one element of the e-book. Here's an example of how a descriptor for a simple book can look:
Name: A Widow's Trace Include: ../indent.css Include: effects.css Content: moments/book.html Author: Aleksandra Łopacińska Date: 2017-04-23T03:38:52+02:00 Language: plAnd here's another one, but this time with comments explaining what's what:
# This e-book's title or name Name: Writing prompt collection # Relative path to image file used for cover Cover: writing_prompts/cover.png # Relative path to image file to put in the e-book on its own Image-Content: writing_prompts/no_the.png # HTML file to put in the e-book after the previous line Content: writing_prompts/theless.html # URL to image file on the internet to put in the e-book on its own Network-Image-Content: https://i.imgur.com/gkevfag.jpg # URL to HTML file on the internet to put in the e-book Network-Content: https://nabijaczleweli.xyz/content/writing_prompts/dead_santa.html # Relative path to a file to pack in the e-book (without displaying it) Include: indent.css # URL to a file on the internet to pack in the e-book (without displaying it) Network-Include: https://nabijaczleweli.xyz/content/assets/common.css # e-book's author (that's you!) Author: nabijaczleweli # e-book's publication date (in RFC3339 format, see below) Date: 2017-02-02T13:45:47+01:00 # e-book content's language (in BCP47 format, see below) Language: en-GB
As you can see, there are four required lines: Name, Author, Date and Language, one or none Cover line, and any number of Content and Image keys. For a complete rundown of all accepted lines, see this table.
first-book ├── rendered │ └── output │ ├── intro.html # ../../rendered/output/intro.html │ ├── main.html # ../../rendered/output/main.html │ └── ending.html # ../../rendered/output/ending.html ├── previews │ └── generated │ └── out │ ├── intro.html # ../../previews/generated/out/intro.html │ └── main.html # ../../previews/generated/out/main.html └── geb └── first ├── intro.html # intro.html └── book.epupp # book.epuppWhen referenced from HTML, their names must be known. The specified names are processed and packed under the names resulting from this algorithm. Packed names of files from the internet is their URL name.
The Date line must be in the RFC3339 format, which, while sounding scary, can be summarised as YYYY-MM-DDTHH:MM:SS+/-TH:TM. Okay, that still looks scary. You can just use the online epoch time converter to convert any date to RFC3339.
If you specify the
--free-date switch as an argument on the command-line,
gen-epub-book will also accept
since these formats might be easier to use,
The Language line must be in the BCP47 format, which effectively means a shorthand for the language in lowercase (en, pl), optionally followed by a hyphen and the language's variant (en-GB).
$ gen-epub-book first-book.epupp first-book.epubAfter which, if you did everything right and
gen-epub-bookdidn't throw you an error, you should now have a file called
first-book.epub. Congratulations! You can now read, verify and convert it using, e.g., Calibre.
The MIT License (MIT) Copyright (c) 2017 nabijaczleweli Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Thank you for making it this far.
I hope that this document is clear and/or informative, if not,
why don't you pop into the issues
into the DMs me an e-mail ?