epubmaker/README.md

epubmaker

Description

A tool that assists in the creation of epub files from html marked source.

Installation

Requires Python 3.10 or later.

git clone <repository-url>
cd epubmaker
pip install .

For development:

pip install -e .
pip install pytest

Usage

python -m epubmaker <source_file> [-f] [-v]

Argument	Description
source_file	Path to the HTML source file
-f, --force	Overwrite an existing output directory
-v, --verbose	Print progress as each step completes

Examples:

# Basic usage
python -m epubmaker mybook.html

# Overwrite a previously generated output
python -m epubmaker -f mybook.html

# Verbose output
python -m epubmaker -v mybook.html

The tool creates an output directory and a .epub file in the current working directory, both named after the value of the Directory: directive in the source file.

Source file format

The source file is an HTML file. Metadata and structure are declared using HTML comment directives. The file must be located in a directory that also contains an Images/ subdirectory.

Required Images/ contents:

• cover.jpeg — cover image
• Inconsolata-Regular.otf, invisible1.ttf, MgOpenModataRegular.ttf — bundled fonts
• Any additional images referenced in the file

Metadata directives

These appear before any section directives. All names in Last, First format.

Directive	Description
<!-- Directory: name -->	Output directory name (required)
<!-- Title: Book Title -->	Book title (required)
<!-- Author: Last, First -->	Author; repeat for multiple authors
<!-- Editor: Last, First -->	Editor
<!-- Artist: Last, First -->	Cover artist
<!-- Publisher: Name -->	Publisher
<!-- Copyright: statement -->	Copyright statement
<!-- ISBN: number -->	ISBN
<!-- UUID: uuid -->	UUID; leave blank to auto-generate
<!-- Source: title -->	Source work
<!-- Subjects: subject, subject -->	Comma-separated subjects
<!-- Series: number Name -->	Series index and name
<!-- Cover: cover.jpeg -->	Cover image filename

Section directives

Each section directive opens a new section. All HTML content that follows — until the next directive — becomes that section's body. The id field is used as the output filename (e.g., ch1 → ch1.xhtml).

<!-- Text: id Section Title -->

Directive	Section type
<!-- TitlePage: id Title -->	Title page
<!-- CopyrightPage: id Title -->	Copyright page
<!-- Dedication: id Title -->	Dedication
<!-- TOC: id Title -->	Table of contents
<!-- Foreward: id Title -->	Foreword
<!-- Text: id Title -->	Body chapter
<!-- Notes: id Title -->	Notes
<!-- Acknowledgement: id Title -->	Acknowledgements
<!-- License: id Title -->	License

Image directive

Used within a section to embed an image. Supported formats: jpg, jpeg, png.

<!-- Image: filename.jpg Alt text::Caption text -->

The caption is optional. To omit it, leave it blank:

<!-- Image: filename.jpg Alt text:: -->

Stylesheet

Link a CSS file using a standard <link> tag and the tool will extract and bundle it:

<link rel="stylesheet" href="path/to/style.css" type="text/css" />

Minimal example

<!-- Directory: mybook -->
<!-- Title: My Book -->
<!-- Author: Smith, Jane -->
<!-- Publisher: My Press -->
<!-- ISBN: 978-0-000-00000-0 -->
<!-- UUID:  -->
<!-- Cover: cover.jpeg -->

<!-- TitlePage: tp My Book -->
<h1>My Book</h1>
<h2>Jane Smith</h2>

<!-- TOC: toc Table of Contents -->
<nav>...</nav>

<!-- Text: ch1 Chapter One -->
<h2>Chapter One</h2>
<p>Body text goes here.</p>

Support

Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.

Roadmap

Modify this code to use pypub.

Authors and acknowledgment

Rory Hinnen

License

GPL 3.0