Convert EPUB3 to TOML

Why Convert EPUB3 to TOML?

Converting EPUB3 e-books to TOML format is useful when you need to extract structured book data into a human-readable configuration format. TOML's clean key-value syntax makes it ideal for representing book metadata, chapter structures, and content catalogs in a format that is easy for both humans and machines to process.

TOML is widely used in modern development ecosystems -- it powers Rust's Cargo.toml, Python's pyproject.toml, and Hugo's static site configuration. By converting EPUB3 content to TOML, you can integrate book data into these toolchains, enabling automated workflows for publishing, cataloging, and content management.

This conversion is particularly valuable for static site generators like Hugo that use TOML for front matter and content configuration. By extracting EPUB3 content into TOML format, you can quickly set up book-related websites, reading lists, or digital library catalogs with properly typed metadata.

The converter maps EPUB3 metadata to TOML tables with typed values: dates are stored as TOML datetime values, language codes as strings, and chapter ordering as integers. Multi-line content is stored using TOML's triple-quoted string syntax, preserving readability.

Key Benefits of Converting EPUB3 to TOML:

• Readable Structure: TOML's clean syntax makes book data easy to read and edit
• Typed Values: Dates, numbers, and booleans are properly typed, not just strings
• Tool Integration: Works with Cargo, Hugo, pyproject.toml ecosystems
• Comment Support: Add annotations and notes to extracted book data
• Metadata Extraction: Clean extraction of title, author, publisher, and dates
• Catalog Building: Create book catalogs and library databases
• Configuration Ready: Output can serve as configuration for book-related applications

Practical Examples

Example 1: Book Metadata Extraction

Input EPUB3 file (novel.epub) — metadata:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>The Innovation Path</dc:title>
  <dc:creator>Alex Johnson</dc:creator>
  <dc:language>en</dc:language>
  <dc:date>2024-03-15</dc:date>
  <dc:publisher>Tech Books Inc.</dc:publisher>
  <dc:subject>Technology</dc:subject>
</metadata>

Output TOML file (novel.toml):

[book]
title = "The Innovation Path"
creator = "Alex Johnson"
language = "en"
date = 2024-03-15
publisher = "Tech Books Inc."
subjects = ["Technology"]

Example 2: Chapter Structure

Input EPUB3 file (textbook.epub) — table of contents:

<nav epub:type="toc">
  <ol>
    <li><a href="ch01.xhtml">Getting Started</a></li>
    <li><a href="ch02.xhtml">Core Concepts</a></li>
    <li><a href="ch03.xhtml">Advanced Topics</a></li>
  </ol>
</nav>

Output TOML file (textbook.toml):

[[chapters]]
title = "Getting Started"
file = "ch01.xhtml"
order = 1

[[chapters]]
title = "Core Concepts"
file = "ch02.xhtml"
order = 2

[[chapters]]
title = "Advanced Topics"
file = "ch03.xhtml"
order = 3

Example 3: Full Book Data with Content

Input EPUB3 file (guide.epub) — complete structure:

<metadata>
  <dc:title>Quick Reference</dc:title>
  <dc:creator>Dev Team</dc:creator>
</metadata>
...
<section epub:type="chapter">
  <h1>Setup</h1>
  <p>Install dependencies first.</p>
</section>

Output TOML file (guide.toml):

[book]
title = "Quick Reference"
creator = "Dev Team"

[[chapters]]
title = "Setup"
order = 1
content = """
Install dependencies first.
"""

Frequently Asked Questions (FAQ)

Q: What is TOML format?

A: TOML (Tom's Obvious Minimal Language) is a configuration file format created by Tom Preston-Werner in 2013. It uses key = value pairs organized in sections (tables) with support for typed values including strings, integers, floats, booleans, dates, arrays, and nested tables. It is used by Cargo (Rust), pyproject.toml (Python), and Hugo.

Q: How is the EPUB3 content structured in TOML?

A: The converter creates a [book] table for metadata (title, author, language, date), a [[chapters]] array of tables for chapter content with title, order, and content fields, and a [[toc]] array for navigation structure. This provides a clean, hierarchical representation of the book data.

Q: How are long text passages stored in TOML?

A: TOML supports multi-line basic strings using triple quotes ("""). Chapter content and long text passages are stored using this syntax, preserving line breaks and paragraphs. This keeps the TOML file readable while accommodating full chapter text content.

Q: Can I use the TOML output with Hugo?

A: Yes, the TOML output can be used as front matter for Hugo static site pages. You can split the output into individual chapter files with TOML front matter to create a book-browsing website. Hugo's native TOML support makes this integration straightforward.

Q: Are dates properly typed in the TOML output?

A: Yes, EPUB3 publication dates are converted to native TOML date values (YYYY-MM-DD format per RFC 3339), not stored as strings. This enables proper date sorting and filtering when processing the TOML data programmatically with TOML parsers in any language.

Q: What happens to EPUB3 multimedia content?

A: Multimedia references (images, audio, video) are stored as file path strings in a [[media]] array of tables, with fields for type, path, and description. The actual binary files are not embedded in TOML. You can use these references to manage media assets separately.

Q: How does TOML compare to JSON for book data?

A: TOML is more human-readable than JSON, supports comments (JSON does not), and has native date types. JSON is more widely supported and better for nested data exchange. For configuration and metadata purposes, TOML is generally preferred; for API data exchange, JSON is more common.

Q: Can I convert the TOML back to EPUB3?

A: TOML stores structured data, not rich document content, so a direct conversion back to EPUB3 would require additional processing. However, the structured TOML data can be used as input for e-book generation tools that build EPUB3 files from metadata and content templates.