Quick Start : Honzo

Getting Started
Quick Start

This guide gets you from zero to a working Honzo file. You will build a simple ebook, inspect its structure, and read it back.

Prerequisites

You need Rust 1.75+ or Node.js 18+. See Installation to set things up.

Create a Honzo File

Rust

CLI

use honzo_io::{HonzoBuilder, Compression, MarkupType};

let hzo = HonzoBuilder::new()
    .meta_title("en", "My First Book")
    .meta_creator("en", "Author Name")
    .add_chapter("Chapter 1: The Beginning", Compression::Lz4, MarkupType::Markdown)
    .add_chapter("Chapter 2: The Middle", Compression::Lz4, MarkupType::Markdown)
    .add_chapter("Chapter 3: The End", Compression::None, MarkupType::Markdown)
    .finalize()
    .unwrap();

std::fs::write("my_book.hzo", hzo).unwrap();
println!("Created my_book.hzo");

honzo-cli make my_book.hzo \
  --title "My First Book" \
  --author "Author Name" \
  --chapters chapter1.md chapter2.md chapter3.md

Inspect the File

Rust

CLI

use honzo_core::HonzoParser;

let data = std::fs::read("my_book.hzo").unwrap();
let p = HonzoParser::new(&data, 1).unwrap();

let head = p.head();
println!("Format version: {}", head.format_version);
println!("Chunk count:    {}", head.chunk_count);
println!("Layout mode:    {}", head.layout_mode);

for entry in p.toc_entries() {
    let tag = std::str::from_utf8(&entry.chunk_type).unwrap();
    let compressed = if entry.compression == 1 { " (lz4)" } else { "" };
    println!("  {tag}: size={}{}", entry.size, compressed);
}

honzo-cli info my_book.hzo

Example output:

Honzo File: my_book.hzo
  Format version: 1
  Chunk count:    5
  Layout mode:    reflowable
  Chunks:
    CHAP  size=184  (lz4)
    COVR  size=24576
    CHAP  size=196  (lz4)
    CHAP  size=172  (none)
    META  size=128

Read Chapters

Rust Parser

Rust Streaming

TypeScript

use honzo_core::HonzoParser;

let data = std::fs::read("my_book.hzo").unwrap();
let p = HonzoParser::new(&data, 1).unwrap();

for entry in p.toc_entries() {
    if &entry.chunk_type == b"CHAP" {
        let chapter_data = p.read_chunk(&entry).unwrap();
        let text = std::str::from_utf8(&chapter_data).unwrap();
        println!("Chapter: {text}");
    }
}

use honzo_io::HonzoStream;

let file = std::fs::File::open("my_book.hzo").unwrap();
let mut stream = HonzoStream::open(file, 1).unwrap();

for chapter in stream.chapters() {
    let (text, _meta) = chapter.unwrap();
    println!("Chapter: {} bytes", text.len());
}

import { createReader } from "@nisoku/honzo";

const response = await fetch("my_book.hzo");
const buf = new Uint8Array(await response.arrayBuffer());
const reader = await createReader(buf);

const meta = reader.getMeta();
console.log("Title:", meta.title?.en);
console.log("Chapters:", reader.chunkCount);

for (let i = 0; i < reader.chunkCount; i++) {
  const chunk = reader.readChunk(i);
  const text = new TextDecoder().decode(chunk);
  console.log("Chapter:", text.substring(0, 100));
}

Convert from EPUB

honzo-cli convert book.epub book.hzo

Or with Rust:

use honzo_convert::convert_epub;

let hzo = convert_epub("book.epub").unwrap();
std::fs::write("book.hzo", hzo).unwrap();

Next Steps

Last updated: Edit this page