{"id":26574204,"url":"https://github.com/devinsterling/rbook","last_synced_at":"2026-05-23T02:10:38.040Z","repository":{"id":65388981,"uuid":"583518259","full_name":"DevinSterling/rbook","owner":"DevinSterling","description":"An ebook library that supports parsing and reading the epub format","archived":false,"fork":false,"pushed_at":"2023-04-09T02:42:30.000Z","size":1930,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-28T08:41:17.542Z","etag":null,"topics":["ebook","ebook-reader","epub","epub2","epub3","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DevinSterling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-12-30T02:38:32.000Z","updated_at":"2025-01-04T14:32:44.000Z","dependencies_parsed_at":"2023-02-19T02:46:03.228Z","dependency_job_id":null,"html_url":"https://github.com/DevinSterling/rbook","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinSterling%2Frbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinSterling%2Frbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinSterling%2Frbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinSterling%2Frbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DevinSterling","download_url":"https://codeload.github.com/DevinSterling/rbook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245044498,"owners_count":20551898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebook","ebook-reader","epub","epub2","epub3","rust"],"created_at":"2025-03-23T01:38:26.354Z","updated_at":"2026-02-24T20:06:37.080Z","avatar_url":"https://github.com/DevinSterling.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rbook\n\n[![Crates.io](https://img.shields.io/crates/v/rbook.svg?logo=rust\u0026style=flat-square)](https://crates.io/crates/rbook)\n[![Documentation](https://img.shields.io/badge/documentation-latest%20release-19e.svg?logo=docs.rs\u0026style=flat-square)](https://docs.rs/rbook)\n[![License](https://img.shields.io/badge/license-Apache%202.0-maroon?logo=apache\u0026style=flat-square)](LICENSE)\n\n![rbook](https://raw.githubusercontent.com/DevinSterling/devinsterling-com/master/public/images/rbook/rbook.png)\n\n\u003e A fast, format-agnostic, ergonomic ebook library with a focus on EPUB.\n\nThe primary goal of `rbook` is to provide an easy-to-use high-level API for handling and editing ebooks.\nMost importantly, this library is designed with future formats in mind\n(`CBZ`, `FB2`, `MOBI`, etc.) via core traits defined within the [ebook](https://docs.rs/rbook/latest/rbook/ebook) \nand [reader](https://docs.rs/rbook/latest/rbook/reader) module, allowing all formats to share the same \"base\" API.\n\n## Documentation\n- [API documentation](https://docs.rs/rbook)\n- [Changelog](CHANGELOG.md)\n\n## Features\nHere is a non-exhaustive list of the features `rbook` provides:\n\n| Feature                     | Overview                                                                                                        | Documentation                                                        |\n|-----------------------------|-----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| **EPUB 2 and 3**            | Simple and advanced read/write view of EPUB `2` and `3` formats.                                                | [epub module](https://docs.rs/rbook/latest/rbook/ebook/epub)         |\n| **Reader**                  | Random‐access or sequential iteration over readable content.                                                    | [reader module](https://docs.rs/rbook/latest/rbook/reader)           |\n| **Detailed Types**          | Abstractions built on expressive traits and types.                                                              |                                                                      |\n| **Metadata**                | Typed access to dates, titles, creators, publishers, languages, tags, roles, attributes, and more.              | [metadata module](https://docs.rs/rbook/latest/rbook/ebook/metadata) |\n| **Manifest**                | Lookup and traverse contained resources such as readable content (XHTML) and images.                            | [manifest module](https://docs.rs/rbook/latest/rbook/ebook/manifest) |\n| **Spine**                   | Chronological reading order and preferred page direction.                                                       | [spine module](https://docs.rs/rbook/latest/rbook/ebook/spine)       |\n| **Table of Contents (ToC)** | Navigation points, including the EPUB 2 guide and EPUB 3 landmarks.                                             | [toc module](https://docs.rs/rbook/latest/rbook/ebook/toc)           |\n| **Resources**               | On-demand retrieval of bytes or strings for any manifest resource; data is not loaded up-front until requested. | [resource module](https://docs.rs/rbook/latest/rbook/ebook/resource) |\n\n### Default crate features\nThese are toggleable features for `rbook` that are\nenabled by default in a project's `Cargo.toml` file:\n\n| Feature        | Description                                                                                           |\n|----------------|-------------------------------------------------------------------------------------------------------|\n| **write**      | Creation and modification of EPUB `2` and `3` formats.                                                |\n| **prelude**    | Convenience [prelude](https://docs.rs/rbook/latest/rbook/prelude) ***only*** including common traits. |\n| **threadsafe** | Enables `Send` + `Sync` constraint for `Epub`.                                                        |\n\n## Usage\n`rbook` can be used by adding it as a dependency in a project's `Cargo.toml` file:\n```toml\n[dependencies]\nrbook = \"0.7.0\"                                           # With default features\n# rbook = { version = \"0.7.0\", default-features = false } # Excluding default features\n```\n\n## WebAssembly\nThe `wasm32-unknown-unknown` target is supported by default.\n\n## Examples\n### Opening and reading an EPUB file\n```rust\nuse rbook::Epub;\n\nfn main() {\n    // Open an epub from a file or directory\n    // * `Read + Seek` implementations supported via `read(...)` for byte streams/buffers\n    let epub = Epub::open(\"example.epub\").unwrap();\n\n    // Create a reader instance \n    // * Configurable via `reader_builder()`\n    let mut reader = epub.reader();\n\n    // Print the readable content\n    for data_result in reader {\n        let data = data_result.unwrap();\n        let kind = data.manifest_entry().kind();\n        assert_eq!(\"application/xhtml+xml\", kind.as_str());\n        assert_eq!(\"xhtml\", kind.subtype());\n        println!(\"{}\", data.content());\n    }\n}\n```\n### Accessing metadata: Retrieving the main title\n```rust\nuse rbook::Epub;\nuse rbook::ebook::metadata::{LanguageKind, TitleKind};\n\nfn main() {\n    let epub = Epub::options()\n        .strict(true) // Enable strict checks (`false` by default)\n        .skip_toc(true) // Skips ToC-related parsing, such as toc.ncx (`false` by default)\n        .open(\"example.epub\")\n        .unwrap();    \n\n    // Retrieve the main title (all titles retrievable via `titles()`)\n    let title = epub.metadata().title().unwrap();\n    assert_eq!(\"Example EPUB\", title.value());\n    assert_eq!(TitleKind::Main, title.kind());\n\n    // Retrieve the first alternate script of a title\n    let alternate_script = title.alternate_scripts().next().unwrap();\n    assert_eq!(\"サンプルEPUB\", alternate_script.value());\n    assert_eq!(\"ja\", alternate_script.language().scheme().code());\n    assert_eq!(LanguageKind::Bcp47, alternate_script.language().kind());\n}\n```\n### Accessing metadata: Retrieving the year and first creator\n```rust\nuse rbook::Epub;\nuse rbook::ebook::metadata::LanguageKind;\n\nfn main() {\n    // If only metadata is needed, skipping helps quicken parsing time and reduce space.\n    let epub = Epub::options()\n        // These flags are `false` by default\n        .skip_toc(true)\n        .skip_manifest(true)\n        .skip_spine(true)\n        .open(\"example.epub\")\n        .unwrap();\n\n    // Retrieve the published date and time\n    let published = epub.metadata().published().unwrap();\n    assert_eq!(2023, published.date().year());\n    assert!(published.time().is_local());\n\n    // Retrieve the first creator\n    let creator = epub.metadata().creators().next().unwrap();\n    assert_eq!(\"John Doe\", creator.value());\n    assert_eq!(Some(\"Doe, John\"), creator.file_as());\n    assert_eq!(0, creator.order());\n\n    // Retrieve the main role of a creator (all roles retrievable via `roles()`)\n    let role = creator.main_role().unwrap();\n    assert_eq!(\"aut\", role.code());\n    assert_eq!(Some(\"marc:relators\"), role.source());\n\n    // Retrieve the first alternate script of a creator\n    let alternate_script = creator.alternate_scripts().next().unwrap();\n    assert_eq!(\"山田太郎\", alternate_script.value());\n    assert_eq!(\"ja\", alternate_script.language().scheme().code());\n    assert_eq!(LanguageKind::Bcp47, alternate_script.language().kind());\n}\n```\n### Extracting images from the manifest\n```rust\nuse rbook::Epub;\nuse std::fs::{self, File};\nuse std::path::Path;\n\nfn main() {\n    let epub = Epub::open(\"example.epub\").unwrap();\n    \n    // Create an output directory for the extracted images\n    let out = Path::new(\"extracted_images\");\n    fs::create_dir_all(\u0026out).unwrap();\n    \n    for image in epub.manifest().images() {\n        // Extract the filename from the href and write to disk\n        let filename = image.href().name().decode(); // Decode as EPUB hrefs are percent-encoded\n\n        // Copy the raw image bytes\n        let file = File::create(out.join(\u0026*filename)).unwrap();\n        image.copy_bytes(file).unwrap();\n    }\n}\n```\n### Editing an EPUB\n```rust\nuse rbook::Epub;\nuse rbook::ebook::errors::EbookResult;\n\nfn main() -\u003e EbookResult\u003c()\u003e {\n    Epub::open(\"old.epub\")?\n        .edit()\n        .creator(\"Jane Doe\") // Adding a creator\n        .write()\n        .compression(9)\n        .save(\"new.epub\")\n}\n```\n### Creating a backwards-compatible EPUB 3 file\n\n\u003e This example uses the high-level builder API.  \n\u003e See the [epub module](https://docs.rs/rbook/latest/rbook/ebook/epub)\n\u003e for lower-level control over the manifest, spine, etc.\n\n```rust\nuse rbook::Epub;\nuse rbook::ebook::errors::EbookResult;\nuse rbook::ebook::toc::TocEntryKind;\nuse rbook::epub::EpubChapter;\nuse std::path::Path;\n\nconst XHTML: \u0026[u8] = b\"\u003cxhtml\u003e...\u003c/xhtml\u003e\"; // Example data\n    \nfn main() -\u003e EbookResult\u003c()\u003e {\n    Epub::builder()\n        .identifier(\"urn:example\")\n        .title(\"Doe Story\")\n        .creator([\"John Doe\", \"Jane Doe\"])\n        .language(\"en\")\n        // Reference a file stored on disk or provide in-memory bytes\n        .cover_image((\"cover.png\", Path::new(\"local/file/cover.png\")))\n        .chapter([\n            // Standard Chapter (Auto-generates href/filename \"volume_i.xhtml\")\n            EpubChapter::new(\"Volume I\").xhtml(XHTML).children(\n                // Providing an explicit href (v1c1.xhtml)\n                EpubChapter::new(\"I: Intro\")\n                    .kind(TocEntryKind::Introduction)\n                    .href(\"v1c1.xhtml\")\n                    .xhtml_body(\"\u003cp\u003eBasic text\u003c/p\u003e\"),\n            ),\n            EpubChapter::new(\"Volume II\").children([\n                // Referencing an XHTML file stored on the OS file system\n                EpubChapter::new(\"I\").href(\"v2/c1.xhtml\").xhtml(Path::new(\"path/to/c1.xhtml\")),\n                // Navigation-only entry linking to a fragment in another chapter\n                EpubChapter::new(\"Section 1\").href(\"v2/c1.xhtml#section-1\"),\n                // Resource included in spine/manifest but omitted from ToC\n                EpubChapter::unlisted(\"v3extras.xhtml\").xhtml(XHTML),\n            ]),\n        ])\n        .write()\n        .compression(0)\n        .save(\"doe_story.epub\") // Save to file or alternative write to memory\n}\n```\n\n\u003e [!TIP]\n\u003e More examples are available in the documentation: \u003chttps://docs.rs/rbook\u003e\n\n## MSRV\nThe current Minimum Supported Rust Version is [1.88.0](https://releases.rs/docs/1.88.0/).\n\n## License\nLicensed under [**Apache License, Version 2.0**](LICENSE).\n\n### Contribution\nUnless you explicitly state otherwise, any contribution intentionally submitted \nfor inclusion in the work by you, as defined in the Apache-2.0 license,\nshall be licensed as above, without any additional terms or conditions.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevinsterling%2Frbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevinsterling%2Frbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevinsterling%2Frbook/lists"}