/text2epub

Text to EPUB converter

Primary LanguageHTMLApache License 2.0Apache-2.0

Text to EPUB converter

text2epub is a simple but powerful tool to convert text to ebooks in EPUB format. It converts text from the following formats:

If your content is already in XHTML-Format (*.xhtml), it will also be included.

When first called, it creates a template epub.xml and exits. You just fill out this file with the metadata (author, title, etc.) and the next time you call text2epub, it will scan for content and create a ebook from it. The files are added alphabetically, so you should add a prefix to sort it (e.g. 01_index.txt, 02_chapter_one.txt, ...). The cover has to be named cover.jpg (or cover.png, cover.gif or cover.svg) and will be embedded in a html file.

Filenames with special character such as whitespace, accents or umlauts will be renamed so the ebook contains only valid filenames in Ascii. This support is somewhat limited, e.g. cyryllic or greek letters wont be replaced. In these cases, rename your files so that they conform to the epub standard.

Stylesheet

You can provide a stylesheet for the complete book or for each content file. The global stylesheet must be named book.css, the other stylesheets <basename>.css. If you don't provide a stylesheet, a default one is embedded.

Table of contents

A table of contents is created by default. text2epub scans for header tags, default is h1, other tags can be specified in the properties.

Internationalization

text2epub has builtin support for english and german. To add support for another language, extract the file Text2Epub_en.properties and rename it to match you language (e.g. Text2Epub_es.properties for spanish). Put that file in the directory where the jar archive is installed. Please send me your translation so I can include it.

Scripting

text2epub uses FreeMarker to create the ebook. You can also use it for scripting. Just place your script inside the content and text2epub will execute it before converting to XHTML. To disable that feature, set the freemarker property to false. There are already some predefined macros you can use:

pagebreak
This macro can be used to place pagebreaks in you ebook, these are references to actual page numbers in the printed version of the book. The first call in each file has to specify the starting page (e.g. <@pagebreak 1/>) in the following calls the page number is automatically increased an can be omitted (<@pagebreak>). If there is at least one pagebreak, text2epub creates a pagemap for the book.
link
Creates a link to another file in the ebook. The macro gets the filename as parameter. The filename is automatically resolved, i.e. you can specify the filename of the source file (e.g. chapter.md) which will be replaced with the filename in the ebook (chapter.xhtml).
refnote
Creates a link to a footnote in another file (default 99_footnotes.xhtml). The macro has three parameters:
note
the id of the footnote (if omitted it gets automatically increased)
linktext
the text shown in the link (default is note)
file
filename containing footnotes (default 99_footnotes.md).
Example: <@refnote 1 "*"/>
footnote
Creates a footnote with a back link to the refnote entry. The macro has three parameters:
note
id of the footnote (if omitted it gets automatically increased)
file
filename which contains the reference (default current file)
linktext
the text shown in the link (default ↑)
Example: <@footnote 1 "chapter01.md" "^">Here is the text</@footnote>
spacer
Creates an empty line. If specified, more lines can be created: <@spacer 3/> creates three empty lines
resolve(srcFilename)
Resolves the given filename of a source file and returns the filename in the ebook. If srcFilename is not known, it will be returned. Example: ${resolve("chapter.md")}

You can access the properties from epub.xml with the expression ${property.<name>} e.g. ${property.title} for the book title.

Customization

Most files are created from FreeMarker templates which are contained in the jar archive. If you want to change these templates, just extract them from the jar using some zip tool and put them in the local directory. Here you can customize them as you wish.

Resources (but not content!) are searched in the following locations:

  1. First they are searched in the local directory where your content resides
  2. Next, all parent directories are scanned
  3. Last the classpath is used

So, if you want to customize a certain resource for all of your books, put the corresponding template in a common base directory or in the same directory where the jar archive is installed.

Prerequisites

text2epub is written in Java, so you have to install a JRE (version 11 or higher). The JRE can be downloaded from here: https://java.com/en/download/

Installation

Just unzip the Jar and the shell script somewhere where it can be accessed. You can put it in its own directory or in an existing one. Add this directory to your PATH variable.

Thats all!

Usage

The shell script has two optional parameters:

  1. Directory containing the content. Defaults to current working directory.
  2. Output file name. Defaults to the filename specified in epub.xml, if not specified "<Title> - <Author>.epub" is used.