@dimitrilahaye/ponybook v1.0.3

@dimitrilahaye/ponybook

What is it?

Ponybook converts html contents into ebook. Each content can come from an url, a file or a string.

Unlike similar node libs, this one is not built around Calibre package. It is a standalone library wrapping @dimitrilahaye/html-to-epub which generate an ebook from scratch.

Table of contents

• How to use it?
• Builder PonybookOptions
• Content PonybookContentOptions
• Use ContentOptionsFormatter
• Use HtmlFormatter
• Use CssFormatter

How to use it?

Install it

npm install @dimitrilahaye/ponybook
# or
yarn add @dimitrilahaye/ponybook

Get the ponybook builder

import Ponybook, { PonybookOptions } from '@dimitrilahaye/ponybook';

const options: PonybookOptions = {
    title: "My brand new book",
    description: "It is my book I am so proud of it",
    publisher: "Myself",
    author: "Me, again",
    cover: "~/absolute/path/to/assets/img/cover.jpg", // (absolute path)
};

const builder = new Ponybook(options);

Build a basic ebook

import Ponybook, { PonybookContentOptions } from '@dimitrilahaye/ponybook';

//...

// aggregate content
builder
    .string("<h1>Super title</h1>", {
        title: "Chapter built from a html string",
    })
    .file("./index.html", {
        title: "Another chapter, but built from a html file",
    })
    .url("https://example.com", {
        title: "Yet another chapter, but built from an url's html content",
    });

// render your ebook at given output path (relative or absolute path)
await builder.render("./path/to/generated-book.epub");

// OR return Buffer

const ebook: Buffer = await builder.buffer();

Builder PonybookOptions

Fonts usage

With PonybookOptions fonts param, if you configure the array to fonts: ['/path/to/Merriweather.ttf'], you can use the following on the PonybookOptions css param:

@font-face {
    font-family: "Merriweather";
    font-style: normal;
    font-weight: normal;
    src : url("./fonts/Merriweather.ttf");
}

Content PonybookContentOptions

Use ContentOptionsFormatter

ContentOptionsFormatter is a callback which give you access to the html content you're processing. It allows you to build then return PonybookContentOptions according to the current content.

const optionsFormatter: ContentOptionsFormatter = (html) => {
    // we assume you are using jsdom
    const dom = new JSDOM(html);
    const author = dom.window.document.querySelector("h1")?.textContent ?? "";

    return {
        title: "My super content title",
        author,
    };
};

ponybook.file(HTML_CONTENT, optionsFormatter);

Use HtmlFormatter

HtmlFormatter is a callback which give you access to the html content you're processing. It allows you to modify the content before to return it.

const htmlFormatter: HtmlFormatter = (html: string) => {
    return `
        ${html}
        <a href="https://example.com/">Hello!</a>
    `;
};

ponybook.file(HTML_CONTENT, options, htmlFormatter);

You may use HtmlFormatter in order to filter which content will be added to the ebook and which will not. Simply return false for content to skip.

const htmlFormatter: HtmlFormatter = (html: string) => {
    const dom = new JSDOM(html);
    const author = dom.window.document.querySelector("h1")?.textContent;

    if (!author) {
        return false;
    }

    return `
        ${html}
        <a href="https://example.com/">Hello!</a>
    `;
};

ponybook.file(HTML_CONTENT, options, htmlFormatter);

Use CssFormatter

CssFormatter is a callback which give you access to css from the first added html content. It allows you to modify it before to return it.

It is used in order to set the final css which will be used as css file for the rendered ebook.

const cssFormatter: CssFormatter = (css) => {
    return `
        ${css}
        h1 { color: blue !important; }
    `;
};

ponybook.css(cssFormatter).file(HTML_CONTENT, options);

You can call builder.css method at any part of your building process. The CssFormatter will always take as argument the css from the first html content you added.

:warning: When you use CssFormatter, it will override the css param you may have setted into builder PonybookOptions.

:warning: In the builder PonybookOptions, resolveCssImportRules param will process only if you use CssFormatter.