BUPE

BUPE is an Elixir EPUB generator and parser with support for EPUB 2 and 3.

Installation

BUPE requires Elixir ~> 1.17 and Erlang/OTP 27 or later.

First, add :bupe to your list of dependencies in mix.exs:

def deps do
  [
    {:bupe, "~> 0.8"}
  ]
end

To check the latest release on Hex, run mix hex.info bupe or visit the bupe page on Hex.pm.

Then update your dependencies:

mix deps.get

Usage

Builder

To create an EPUB file:

pages = "~/book/*.xhtml" |> Path.expand() |> Path.wildcard()
config = BUPE.Config.new(%{
  title: "Sample",
  language: "en",
  creator: "John Doe",
  publisher: "Sample",
  pages: pages
})
BUPE.build(config, "sample.epub")
# {:ok, "/Users/dev/sample.epub"}

If you prefer, you can build the EPUB document in memory:

BUPE.build(config, "sample.epub", [:memory])

For more control over pages, you can provide a list of BUPE.Item structs instead of a list of strings:

pages = [
  %BUPE.Item{
    href: "/Users/dev/book/bacon.xhtml",
    description: "Ode to Bacon"
  }
]

The description is used in the EPUB Table of Contents; if you omit it, BUPE derives a default description from the file name.

The language must be a valid BCP 47 language tag (e.g. "en", "pt-BR"); BUPE.build/3 raises BUPE.InvalidLanguage when the tag is invalid.

If a page includes JavaScript, use the properties field in BUPE.Item:

pages = [
  %BUPE.Item{
    href: "/Users/dev/book/bacon.xhtml",
    description: "Ode to Bacon",
    properties: "scripted"
  }
]

Keep in mind that if you add the scripted property to a page without JavaScript, you will see warnings from validation tools such as EPUBCheck.

See BUPE.build/3, BUPE.Config, and BUPE.Item for details.

Using the builder via command line

You can build EPUB documents from the command line as follows:

1. Install BUPE as an escript:

mix escript.install hex bupe

2. Then use it in your projects:

bupe "EPUB_TITLE" -p egg.xhtml -p bacon.xhtml -l path/to/logo.png

For more details on the command-line tool, review the usage guide:

bupe --help

Parser

To parse an EPUB file:

BUPE.parse("Elixir.epub")

See BUPE.parse/1 for details.

Copyright and License

Copyright 2025 Milton Mazzarri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.