npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@eit6609/epub-creator

v1.0.1

Published

A creator of ePUB 2.0 ebooks

Downloads

5

Readme

ePUB Creator

ePUB Creator lets you create an ePUB 2.0 ebook from a directory.

It accepts a directory with the whole content of the ebook (XHTML pages, images, stylesheets, etc.) and, with some configuration, zips it up to an ePUB.

This lets you create and test your content with a local browser and, only after it works and it looks like you want, proceed to create the ePUB. And, at least for me, this is the right way to do it.

Run this to install:

npm i @eit6609/epub-creator

Example

Let's start with an example.

Suppose that:

  • your content is located in the /odissey directory
  • the spine (the linear reading order) is made by these files in the content directory: front.html, book01.html, book02.html, ..., book23.html, book24.html, end.html
  • you want a TOC (Table Of Contents) that lists all the 24 "books"
  • you want to use the file images/cover.jpg in the content directory as the cover of the book, and automatically add a cover page at the beginning of the spine
  • you want to set the author and the title of the ebook but you don't care about the complete metadata
  • you want the result in a file named odissey.epub

This is what you need to do:

const { EPUBCreator } = require('@eit6609/epub-creator');

const spine = ['front.html'];
const toc = [];
for (let i = 1, i <= 24; i++) {
    const number = i < 10 ? `0${i}` : `${i}`;
    const fileName = `book${number}.html`;
    spine.push(fileName);
    toc.push([{ label: `Book ${i}`, href: fileName }]);
}
spine.push('end.html');

const options = {
    contentDir: '/odissey',
    spine,
    toc,
    cover: 'images/cover.jpg',
    simpleMetadata: {
        author: 'Homer',
        title: 'Odissey'
    }
};

const creator = new EPUBCreator(options);
creator.create('odissey.epub')
    .catch((error) => console.log(error));

Of course, the real world is more complex than that, so let's see in detail what you can do to configure the EPUBCreator instance.

API Reference

constructor(options: object)

Creates an instance of EPUBCreator with the required options. Read on for the definition of the options object.

async create(fileName: string): empty promise

Creates the ePUB with the given file name.

Metadata

According to the specs, three metadata elements are required:

  • dc:title
  • dc:identifier
  • dc:language

If you don't provide a value for them, they will get these default values:

An optional metadata element, dc:date, is also provided with a default value, the current date.

You can provide the most common metadata elements using a shortcut: the simpleMetadata option.

You can also provide the full metadata, if you need more control: these elements are merged with the simpleMetadata generated elements but have precedence over them.

Options Reference

contentDir, string, required

It is the directory where your content (XHTML, images, stylesheets, fonts, etc.) is located.

The value can be a full path or a relative path.

All the file names that you may use in the options are relative to this directory.

All the files and subdirectories of the directory will be included in the ePUB, and a manifest will be generated that lists all of them.

spine, array, required

The spine of an ePUB defines the linear reading order, i.e., the sequence of files that will be opened when you turn the pages.

You configure the spine providing an array of file names.

Remember that all the files potentially reachable by any reference mechanism must be included in the spine.

toc, array, required

The TOC is a hierarchical table of contents in a compact tree representation that is used to generate the NCX of the ePUB.

  • the node of the tree is an array with this structure:
    • the first item is an object with these properties:
      • label, required string: the text of the link
      • href, required string: the name of the file, possibly containing a fragment specification
    • there can be items besides the first representing the children of the node, which are nodes in turn
  • the TOC is an array of nodes.

Example

Suppose that the logical structure of the TOC is this:

  • Front Matter
  • Chapter 1
    • Section 1.1
    • Section 1.2
  • Chapter 2

You represent the TOC with this array of nodes:

const toc = [
    [{ label: 'Front Matter', href: 'front.html' }],
    [{ label: 'Chapter 1', href: 'chapter1.html' },
        [{ label: 'Section 1.1', href: 'chapter1.html#section1.1' }],
        [{ label: 'Section 1.2', href: 'chapter1.html#section1.2' }]
    ],
    [{ label: 'Chapter 2', href: 'chapter2.html' }]
];

cover, string, optional

If you provide the name of an image file as the value of this property, you will get the following:

  • the image becomes the cover of the ePUB
  • a page that displays the image is created and added at the beginning of the spine

simpleMetadata, object, optional

Use this object to easily configure the most common metadata.

Its properties are:

  • title, string, optional, generates the dc:title element
  • author, string, optional, generates the dc:creator element
  • language, string, optional, generates the dc:language element

Example

const simpleMetadata = {
	title: 'Un libro',
	author: 'Un autore',
	language: 'it'
};

The resulting metadata element of the content.opf file will be something like:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
    <dc:date>2019-11-19T11:22:50.448Z</dc:date>
    <dc:identifier id="BookId" opf:scheme="uuid">d5f9547e-b630-4c01-86a1-5cd11b226776</dc:identifier>
    <dc:language>it</dc:language>
    <dc:title>Un libro</dc:title>
    <dc:creator opf:role="aut">Un autore</dc:creator>
</metadata>

You can see that the elements dc:date and dc:identifier have been provided with default values as described above.

metadata, array, optional

If you need full control over the metadata you can use this property. What you provide is an array of XML elements, in JSML format, that will be merged with the simpleMetadata and will become the children of the metadata element of the content.opf file.

Example

const metadata = [
    ['dc:identifier', { id: 'BookId', 'opf:scheme': 'ISBN' }, 'XXXXXXXXXX'],
    ['dc:contributor', { 'opf:role': 'edt' }, 'An Editor']
];
const simpleMetadata = {
	title: 'A Book',
	author: 'An Author'
};

The resulting metadata element will be something like:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
    <dc:date>2019-11-19T11:22:50.448Z</dc:date>
    <dc:identifier id="BookId" opf:scheme="ISBN">XXXXXXXXXX</dc:identifier>
    <dc:language>en</dc:language>
    <dc:title>A Book</dc:title>
    <dc:creator opf:role="aut">An Author</dc:creator>
    <dc:contributor opf:role="edt">An Editor</dc:creator>
</metadata>

You can see that the element dc:date has been provided with a default value as described above and that the metadata elements have been merged with the simpleMetadata generated elements.