Epubook

https://github.com/yjl9903/epubook
Admin
Epubook is a Node.js EPUB 3 generation library that provides both low-level API and high-level ebook...
Tokens:10,025
Snippets:130
Trust Score:9.6
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install and use @epubook/cli

Source: https://github.com/yjl9903/epubook/blob/main/packages/cli/README.md

Install the package globally and run the conversion command on a markdown file.

```bash
npm i -g @epubook/cli

epubook content.md
```

--------------------------------

### Install @epubook/core

Source: https://github.com/yjl9903/epubook/blob/main/packages/core/README.md

Install the package via npm.

```bash
npm i @epubook/core
```

--------------------------------

### Install and use epubook CLI

Source: https://github.com/yjl9903/epubook/blob/main/README.md

Commands for installing the CLI globally and checking version or help information.

```bash
npm i -g @epubook/cli

epubook --version

epubook --help
```

--------------------------------

### Install epubook library

Source: https://github.com/yjl9903/epubook/blob/main/README.md

Command to install the epubook package via npm.

```bash
npm i epubook
```

--------------------------------

### Install @epubook/xml

Source: https://github.com/yjl9903/epubook/blob/main/packages/xml/README.md

Use npm to add the package to your project dependencies.

```bash
npm i @epubook/xml
```

--------------------------------

### Create New Ebook Instance with Epubook.create

Source: https://context7.com/yjl9903/epubook/llms.txt

Initializes a new ebook with essential metadata. Use this method to start creating an ebook.

```typescript
import { Epubook } from 'epubook';

const book = await Epubook.create({
  title: 'My First Ebook',
  description: 'A sample ebook created with Epubook',
  language: 'en-US',
  author: [
    { name: 'John Doe', fileAs: 'Doe, John' }
  ],
  date: new Date('2024-01-15'),
  lastModified: new Date('2024-01-20'),
  subject: 'Fiction',
  publisher: 'Self Published',
  source: 'Original Work'
});

// book is now ready for adding cover, pages, and table of contents
```

--------------------------------

### Generate EPUB with epubook

Source: https://github.com/yjl9903/epubook/blob/main/README.md

Example of creating an EPUB file using the high-level Epubook API.

```ts
import { Epubook } from 'epubook'

const ebook = await Epubook.create({
  title: 'title',
  description: 'something'
})

const cover = await ebook.cover('./assets/cover.jpg')
const main = ebook.page('chapter', { title: 'Main', content: 'Hello, World!' })

ebook.toc(cover, main)

await ebook.writeFile('./output.epub')
```

--------------------------------

### Epubook CLI Commands

Source: https://context7.com/yjl9903/epubook/llms.txt

Common CLI operations for managing EPUB files, including installation, bundling, extraction, and compression.

```bash
# Install CLI globally
npm install -g @epubook/cli

# Check version
epubook --version

# Get help
epubook --help

# Bundle a document to EPUB
epubook input.md --output book.epub

# Bundle with custom theme
epubook input.md --theme @epubook/theme-custom --output book.epub

# Extract an existing EPUB
epubook extract book.epub --out-dir ./extracted/

# Compress a directory back to EPUB
epubook compress ./extracted/ --output repackaged.epub
```

--------------------------------

### Get Ebook as Uint8Array with Epubook

Source: https://context7.com/yjl9903/epubook/llms.txt

The `bundle()` method returns the EPUB content as a Uint8Array, suitable for streaming, database storage, or in-memory processing without direct filesystem access.

```typescript
import { Epubook } from 'epubook';
import * as fs from 'node:fs';

const book = await Epubook.create({
  title: 'Streamable Ebook',
  description: 'For in-memory processing'
});

const cover = await book.cover('./cover.jpg');
const page = book.page('chapter', { title: 'Content', content: 'Chapter text...' });
book.toc(cover, page);

// Get EPUB as Uint8Array
const epubData = await book.bundle();

// Use the data as needed
fs.writeFileSync('./output.epub', epubData);
// Or send as HTTP response, store in database, etc.
```

--------------------------------

### Initialize and Write EPUB

Source: https://github.com/yjl9903/epubook/blob/main/packages/core/README.md

Configure book metadata, add content to the spine, and export to a file.

```ts
import { Epub, HTML } from '@epubook/core'

const book = new Epub({
  title: 'Test Book',
  date: new Date('2023-02-01T11:00:00.000Z'),
  lastModified: new Date('2023-02-26T11:00:00.000Z'),
  creator: 'XLor',
  description: 'for test usage',
  source: 'imagine'
})

const page = new HTML('start.xhtml', '...')

book.item(page).spine(page).toc([{ title: 'Start', page }])

await book.writeFile('./test.epub')
```

--------------------------------

### Epubook.create

Source: https://context7.com/yjl9903/epubook/llms.txt

Initializes a new ebook instance with metadata.

```APIDOC
## Epubook.create

### Description
Initializes a new ebook with metadata including title, description, author information, publication dates, and language settings.

### Parameters
#### Request Body
- **title** (string) - Required - The title of the ebook
- **description** (string) - Optional - A brief description of the ebook
- **language** (string) - Optional - The language code (e.g., 'en-US')
- **author** (array) - Optional - List of authors with name and fileAs properties
- **date** (Date) - Optional - Publication date
- **lastModified** (Date) - Optional - Last modified date
- **subject** (string) - Optional - Subject or genre
- **publisher** (string) - Optional - Publisher name
- **source** (string) - Optional - Source of the work

### Request Example
{
  "title": "My First Ebook",
  "description": "A sample ebook created with Epubook",
  "language": "en-US",
  "author": [{ "name": "John Doe", "fileAs": "Doe, John" }]
}

### Response
#### Success Response (200)
- **book** (Epubook) - An initialized Epubook instance
```

--------------------------------

### Generate a complete EPUB file

Source: https://context7.com/yjl9903/epubook/llms.txt

Initializes an ebook with metadata, adds a cover, creates chapters, defines the table of contents, and writes the final file to disk.

```typescript
import * as fs from 'node:fs';
import { Epubook, XHTML } from 'epubook';

async function createEbook() {
  // Initialize ebook with full metadata
  const book = await Epubook.create({
    title: 'The Complete Guide',
    description: 'A comprehensive guide demonstrating Epubook capabilities',
    language: 'en-US',
    author: [
      { name: 'Primary Author', fileAs: 'Author, Primary' },
      { name: 'Contributing Author', fileAs: 'Author, Contributing' }
    ],
    date: new Date('2024-01-01'),
    lastModified: new Date(),
    subject: 'Technology',
    publisher: 'Tech Publications',
    source: 'Original Content'
  });

  // Add cover image
  const cover = await book.cover('./assets/cover.jpg');

  // Create front matter
  const preface = book.page('chapter', {
    title: 'Preface',
    content: `Welcome to this comprehensive guide.
This book will walk you through all the essential concepts.
We hope you find it useful and informative.`
  });

  // Create main content chapters
  const chapters: XHTML[] = [];

  const ch1 = book.page('chapter', {
    title: 'Chapter 1: Getting Started',
    content: `This chapter covers the basics.
First, ensure you have all prerequisites installed.
Then, follow the step-by-step instructions.
By the end, you'll have a working setup.`
  });
  chapters.push(ch1);

  const ch2 = book.page('chapter', {
    title: 'Chapter 2: Core Concepts',
    content: `Understanding the fundamentals is crucial.
Let's explore the key principles.
Each concept builds upon the previous one.
Take your time to absorb the material.`
  });
  chapters.push(ch2);

  const ch3 = book.page('chapter', {
    title: 'Chapter 3: Advanced Topics',
    content: `Now we dive into advanced territory.
These techniques require solid foundational knowledge.
Practice each example carefully.
Mastery comes with repetition and experimentation.`
  });
  chapters.push(ch3);

  // Create back matter
  const appendix = book.page('chapter', {
    title: 'Appendix: Quick Reference',
    content: `Here's a summary of key points.
Refer back to this section as needed.
Happy reading!`
  });

  // Build table of contents with sections
  book.toc(
    cover,
    preface,
    { title: 'Main Content', list: chapters },
    appendix
  );

  // Export the final EPUB
  await book.writeFile('./output/complete-guide.epub');

  console.log('EPUB created successfully!');
}

createEbook().catch(console.error);
```

--------------------------------

### Generate EPUB with Epub class

Source: https://context7.com/yjl9903/epubook/llms.txt

Use the Epub class for fine-grained control over manifest, spine, and navigation. Requires manual XHTML string creation.

```typescript
import { Epub, XHTML, Image, StyleSheet } from '@epubook/core';

const book = new Epub({
  title: 'Low-Level EPUB',
  date: new Date('2024-01-15'),
  lastModified: new Date('2024-01-20'),
  creator: { name: 'Developer', fileAs: 'Developer' },
  description: 'Created with low-level API',
  source: 'Custom source'
});

// Create XHTML content manually
const pageContent = `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title>Chapter 1</title></head>
<body>
  <h1>Chapter 1</h1>
  <p>This is the first paragraph.</p>
</body>
</html>`;

const page = new XHTML('text/chapter1.xhtml', { title: 'Chapter 1', language: 'en' }, pageContent);

// Add to manifest and spine
book.item(page);
book.spine(page);

// Set up navigation
book.toc([{ title: 'Chapter 1', page }]);

// Write the EPUB file
await book.writeFile('./low-level-output.epub');
```

--------------------------------

### ebook.page

Source: https://context7.com/yjl9903/epubook/llms.txt

Creates XHTML content pages using theme templates.

```APIDOC
## ebook.page

### Description
Creates XHTML content pages using theme templates. The default 'chapter' template accepts a title and content string.

### Parameters
#### Request Body
- **template** (string) - Required - The name of the template to use
- **properties** (object) - Required - Template-specific properties (e.g., title, content)

### Request Example
book.page('chapter', {
  "title": "Chapter 1",
  "content": "Content text here."
});

### Response
#### Success Response (200)
- **page** (Page) - The created content page object
```

--------------------------------

### Configure JSX Import Source

Source: https://github.com/yjl9903/epubook/blob/main/packages/xml/README.md

Add this pragma at the top of your JSX or TSX files to enable @epubook/xml support.

```ts
/** @jsxImportSource @epubook/xml */
```

--------------------------------

### Create Content Pages with ebook.page

Source: https://context7.com/yjl9903/epubook/llms.txt

Generates XHTML content pages using specified theme templates. The default 'chapter' template accepts title and content, automatically formatting content into paragraphs.

```typescript
import { Epubook } from 'epubook';

const book = await Epubook.create({
  title: 'Sample Novel',
  description: 'A multi-chapter novel'
});

const cover = await book.cover('./cover.jpg');

// Create chapter pages with the default 'chapter' template
const chapter1 = book.page('chapter', {
  title: 'Chapter 1: The Beginning',
  content: `It was a dark and stormy night.
The wind howled through the trees.
Our hero stood at the crossroads, uncertain of which path to take.`
});

const chapter2 = book.page('chapter', {
  title: 'Chapter 2: The Journey',
  content: `The next morning brought clear skies.
With renewed determination, the journey continued.
Each step brought new discoveries.`
});

const chapter3 = book.page('chapter', {
  title: 'Chapter 3: The Conclusion',
  content: `At last, the destination was reached.
All the struggles had been worth it.
The end.`
});
```

--------------------------------

### ebook.cover

Source: https://context7.com/yjl9903/epubook/llms.txt

Adds a cover image to the ebook instance.

```APIDOC
## ebook.cover

### Description
Adds a cover image to the ebook from either a file path or a Uint8Array buffer. Automatically creates the cover XHTML page.

### Parameters
#### Request Body
- **image** (string|Uint8Array) - Required - File path or buffer containing the image
- **extension** (string) - Optional - File extension if using a buffer

### Request Example
// Add cover from file path
book.cover('./images/cover.jpg');

### Response
#### Success Response (200)
- **cover** (Cover) - A Cover object that can be included in the table of contents
```

--------------------------------

### Build XHTML content using JSX

Source: https://context7.com/yjl9903/epubook/llms.txt

Enable JSX support with the @jsxImportSource pragma to define XHTML content using a declarative, React-like syntax.

```tsx
/** @jsxImportSource @epubook/xml */

import { XHTMLBuilder } from '@epubook/xml';

const builder = new XHTMLBuilder('text/styled-chapter.xhtml');

// Use JSX to build content
builder
  .setTitle('JSX Chapter')
  .setLanguage('en')
  .appendStyleSheet('../styles/main.css');

// JSX elements are converted to XHTML nodes
const content = (
  <>
    <h1>Chapter Title</h1>
    <p class="lead">This is a lead paragraph with special styling.</p>
    <p>Regular paragraph content goes here.</p>
    <blockquote>
      <p>A quoted section for emphasis.</p>
    </blockquote>
    <ul>
      <li>First item</li>
      <li>Second item</li>
      <li>Third item</li>
    </ul>
  </>
);

builder.appendBody(content);
const result = builder.build();
```

--------------------------------

### Export Ebook to EPUB File with Epubook

Source: https://context7.com/yjl9903/epubook/llms.txt

Use `writeFile()` to package and save the complete EPUB file to a specified path. This method handles all necessary EPUB packaging and ZIP compression.

```typescript
import { Epubook } from 'epubook';

const book = await Epubook.create({
  title: 'Complete Ebook',
  description: 'Ready for export',
  author: [{ name: 'Author Name' }],
  language: 'en-US'
});

const cover = await book.cover('./cover.jpg');
const chapter1 = book.page('chapter', { title: 'Chapter 1', content: 'Content here...' });
const chapter2 = book.page('chapter', { title: 'Chapter 2', content: 'More content...' });

book.toc(cover, chapter1, chapter2);

// Write the final EPUB file
await book.writeFile('./output/my-ebook.epub');
// Creates a valid EPUB 3 file ready for distribution
```

--------------------------------

### Build Table of Contents with Epubook

Source: https://context7.com/yjl9903/epubook/llms.txt

Use the `toc()` method to construct the navigation document and define the reading order. It supports both flat and grouped structures for chapters and sections.

```typescript
import { Epubook, XHTML } from 'epubook';

const book = await Epubook.create({
  title: 'Organized Novel',
  description: 'A well-structured ebook with sections'
});

const cover = await book.cover('./cover.jpg');

// Create multiple chapters
const intro = book.page('chapter', { title: 'Introduction', content: 'Welcome to this book...' });
const ch1 = book.page('chapter', { title: 'Chapter 1', content: 'First chapter content...' });
const ch2 = book.page('chapter', { title: 'Chapter 2', content: 'Second chapter content...' });
const ch3 = book.page('chapter', { title: 'Chapter 3', content: 'Third chapter content...' });
const epilogue = book.page('chapter', { title: 'Epilogue', content: 'Final thoughts...' });

// Simple flat table of contents
book.toc(cover, intro, ch1, ch2, ch3, epilogue);

// Alternative: Grouped table of contents with sections
book.toc(
  cover,
  intro,
  { title: 'Part One', list: [ch1, ch2] },
  { title: 'Part Two', list: [ch3] },
  epilogue
);
```

--------------------------------

### Construct XHTML with XHTMLBuilder

Source: https://context7.com/yjl9903/epubook/llms.txt

Utilize the fluent API of XHTMLBuilder to programmatically define document structure, metadata, and body content.

```typescript
import { XHTMLBuilder } from '@epubook/xml';

// Create an XHTML document programmatically
const builder = new XHTMLBuilder('text/chapter.xhtml');

builder
  .setTitle('My Chapter')
  .setLanguage('en')
  .appendStyleSheet('../styles/main.css')
  .appendBody({
    type: 'element',
    name: 'h1',
    attributes: {},
    children: [{ type: 'text', value: 'Chapter Title' }]
  })
  .appendBody({
    type: 'element',
    name: 'p',
    attributes: { class: 'intro' },
    children: [{ type: 'text', value: 'This is the introduction paragraph.' }]
  });

const result = builder.build();
// result.filename: 'text/chapter.xhtml'
// result.meta: { title: 'My Chapter', language: 'en' }
// result.content: Full XHTML string with proper namespaces
```

--------------------------------

### Add Images to Ebook Content with Epubook

Source: https://context7.com/yjl9903/epubook/llms.txt

The `image()` method registers images in the ebook's manifest. It accepts file paths or Uint8Array buffers and returns a Promise resolving to an Image resource for use in custom XHTML.

```typescript
import { Epubook } from 'epubook';
import * as fs from 'node:fs';

const book = await Epubook.create({
  title: 'Illustrated Guide',
  description: 'A book with images'
});

// Add image from file path
const diagram1 = await book.image('./images/diagram1.png');

// Add image from buffer
const imageData = fs.readFileSync('./images/photo.jpg');
const photo = await book.image(new Uint8Array(imageData), 'jpg');

// Images are now in the manifest and can be referenced in custom pages
```

--------------------------------

### Generate XHTML with JSX

Source: https://github.com/yjl9903/epubook/blob/main/packages/core/README.md

Use JSX syntax to construct XHTML nodes for book content.

```tsx
/** @jsxImportSource @epubook/xml */

import { XHTMLBuilder } from '@epubook/core'

const builder = new XHTMLBuilder()

const xhtml = builder
  .appendBody(<h1>Title</h1>)
  .appendBody(<p>This is a paragraph</p>)
  .build()
```

--------------------------------

### Extend Epubook with Custom Templates

Source: https://context7.com/yjl9903/epubook/llms.txt

Use the extend method to register custom page templates that return an XHTMLBuilder. These templates can then be instantiated using the page method.

```typescript
import { Epubook, XHTMLBuilder } from 'epubook';

const book = await Epubook.create({
  title: 'Custom Themed Book',
  description: 'Using custom page templates'
});

// Extend with custom templates
const extendedBook = book.extend({
  pages: {
    // Custom title page template
    titlePage: (file: string, props: { title: string; subtitle: string; author: string }) => {
      return new XHTMLBuilder(file)
        .setTitle(props.title)
        .appendBody({
          type: 'element',
          name: 'div',
          attributes: { class: 'title-page' },
          children: [
            { type: 'element', name: 'h1', attributes: {}, children: [{ type: 'text', value: props.title }] },
            { type: 'element', name: 'h2', attributes: {}, children: [{ type: 'text', value: props.subtitle }] },
            { type: 'element', name: 'p', attributes: { class: 'author' }, children: [{ type: 'text', value: props.author }] }
          ]
        });
    },
    // Custom dedication page template
    dedication: (file: string, props: { text: string }) => {
      return new XHTMLBuilder(file)
        .setTitle('Dedication')
        .appendBody({
          type: 'element',
          name: 'div',
          attributes: { class: 'dedication' },
          children: [{ type: 'element', name: 'p', attributes: {}, children: [{ type: 'text', value: props.text }] }]
        });
    }
  }
});

// Use custom templates
const titlePage = extendedBook.page('titlePage', {
  title: 'My Novel',
  subtitle: 'A Story of Adventure',
  author: 'Jane Author'
});

const dedication = extendedBook.page('dedication', {
  text: 'For my family, who always believed in me.'
});

const chapter1 = extendedBook.page('chapter', { title: 'Chapter 1', content: 'Story begins...' });

extendedBook.toc(titlePage, dedication, chapter1);
await extendedBook.writeFile('./custom-book.epub');
```

--------------------------------

### Add Cover Image to Ebook

Source: https://context7.com/yjl9903/epubook/llms.txt

Adds a cover image from a file path or buffer. This method automatically generates the cover XHTML and marks the image with the EPUB cover-image property.

```typescript
import { Epubook } from 'epubook';

const book = await Epubook.create({
  title: 'Adventure Novel',
  description: 'An exciting adventure story'
});

// Add cover from file path
const cover = await book.cover('./images/cover.jpg');

// Alternative: Add cover from buffer with explicit extension
import * as fs from 'node:fs';
const imageBuffer = fs.readFileSync('./images/cover.png');
const coverFromBuffer = await book.cover(new Uint8Array(imageBuffer), 'png');
```
Tokens:
Raw