easydoc

Rust DOC/DOCX document operations library -- read, write, template fill, Markdown conversion, and streaming event processing with O(1) memory.

English | 简体中文

Positioning · Capabilities · Which Crate · Quick Start · API · Derive · Quality · Upstream · License

Current version: 0.1.0-alpha.1 MSRV: Rust 1.88 Edition: 2024 Workspace Resolver: 3 Maturity: Alpha (public API may change) Last verified: 2026-08-11

1. Project Positioning & Status

1.1 What It Is

easydoc is the facade crate for the easydoc-rust workspace -- a Rust library for DOC/DOCX document operations. It provides a single EasyDoc static factory (18 methods) that delegates to 7 domain-specific sub-crates.

1.2 What It Is Not

• Not a DOCX parser by itself -- parsing is delegated to easydoc-reader (via office_oxide).
• Not a DOCX generator by itself -- generation is delegated to easydoc-writer (via docx-rs).
• Not an Excel library -- for XLSX operations, use easyexcel-rust.
• Not a PDF or ODT processor -- only DOCX (full) and DOC (read-only) are supported.

1.3 Status Evidence

2. Capabilities & Maturity

2.1 Capability Matrix

2.2 Status Definitions

2.3 Format Support Matrix

3. Which Crate to Depend On

The easydoc-rust workspace contains 9 crates. Most users should depend on easydoc (this crate).

# Most users: depend on the facade
[dependencies]
easydoc = "0.1.0-alpha.1"

# Advanced: depend on a single domain crate
easydoc-core = "0.1.0-alpha.1"

4. Workspace Architecture

Application / downstream crate
        │ cargo add easydoc
        ▼
┌───────────────────────────────────────────────────────┐
│ easydoc-rust Cargo Workspace (9 crates)               │
│                                                       │
│ easydoc               Facade -- EasyDoc static factory│
│ easydoc-core          Traits, data model, errors      │
│ easydoc-derive        #[derive(DocxRow)] proc-macro   │
│ easydoc-ooxml         Safe OOXML rewrite, atomic I/O  │
│ easydoc-reader        DOC/DOCX reading (office_oxide) │
│ easydoc-writer        DOCX creation (docx-rs)         │
│ easydoc-template      Template placeholder fill       │
│ easydoc-markdown      DOC/DOCX → Markdown             │
│ easydoc-mcp           MCP server for LLM agents       │
└───────────────────────────────────────────────────────┘
        │
        ▼
[DOCX files / DOC files / in-memory bytes]

flowchart TB
    USER["Application"] --> FACADE["easydoc (facade)"]
    FACADE --> CORE["easydoc-core"]
    FACADE --> DERIVE["easydoc-derive"]
    FACADE --> READER["easydoc-reader"]
    FACADE --> WRITER["easydoc-writer"]
    FACADE --> TEMPLATE["easydoc-template"]
    FACADE --> MARKDOWN["easydoc-markdown"]
    DERIVE --> CORE
    READER --> CORE
    WRITER --> CORE
    WRITER --> OOXML["easydoc-ooxml"]
    TEMPLATE --> CORE
    TEMPLATE --> OOXML
    MARKDOWN --> CORE
    MARKDOWN --> READER
    MARKDOWN --> OOXML

4.1 Facade Re-export Map

5. Quick Start

5.1 Installation

[dependencies]
easydoc = "0.1.0-alpha.1"

5.2 Write a Table from Struct Data

use easydoc::prelude::*;

#[derive(DocxRow)]
#[docx(banded_rows = true)]
struct User {
    #[docx(name = "Name", order = 0, width = "30%")]
    name: String,
    #[docx(name = "Age", order = 1, width = "15%")]
    age: u32,
    #[docx(name = "Email", order = 2, width = "55%")]
    email: String,
}

let users = vec![
    User { name: "Alice".into(), age: 30, email: "alice@example.com".into() },
    User { name: "Bob".into(), age: 25, email: "bob@example.com".into() },
];

EasyDoc::write_table("users.docx", &users)
    .title("User Report")
    .banded_rows(true)
    .do_write()?;
# Ok::<(), easydoc::DocError>(())

5.3 Read a Document (Streaming, O(1) Memory)

use easydoc::prelude::*;

// Quick text extraction
let text = EasyDoc::read_text("document.docx")?;

// Typed table extraction
let tables: Vec<Vec<User>> = EasyDoc::read_tables::<User>("document.docx")?;

// SAX event streaming -- O(1) memory
struct MySink;
impl EventSink for MySink {
    fn on_event(&mut self, event: &DocumentEvent) -> easydoc::Result<()> {
        match event {
            DocumentEvent::Heading { level, runs } => {
                let text: String = runs.iter().map(|r| r.text.as_str()).collect();
                println!("H{level}: {text}");
            }
            _ => {}
        }
        Ok(())
    }
}

EasyDoc::read_events("large.docx", &mut MySink)?;
# Ok::<(), easydoc::DocError>(())

5.4 Convert to Markdown

use easydoc::prelude::*;

// Quick conversion
let markdown = EasyDoc::to_markdown("document.docx")?;

// Full control
let result = EasyDoc::markdown("document.docx")
    .image_directory("output/assets")
    .include_front_matter(true)
    .write_to("output/document.md")?;
# Ok::<(), easydoc::DocError>(())

5.5 Build a Full Document

use easydoc::prelude::*;

EasyDoc::document("report.docx")
    .title("Annual Report")
    .author("Zhang San")
    .add_heading("Chapter 1", HeadingLevel::H1)
    .add_paragraph(
        Paragraph::new()
            .add_text("Body text with ")
            .add_run(Run::new("bold").bold())
            .add_text(" content.")
    )
    .add_page_break()
    .build()?
    .save()?;
# Ok::<(), easydoc::DocError>(())

5.6 Template Fill

use easydoc::EasyDoc;
use std::collections::HashMap;

let mut data = HashMap::new();
data.insert("name".into(), "Alice".into());
data.insert("date".into(), "2026-08-11".into());

EasyDoc::fill_template("template.docx", "output.docx", &data)?;
# Ok::<(), easydoc::DocError>(())

5.7 Semantic Model Round-Trip

use easydoc::EasyDoc;

// Read -> Modify -> Write
let mut content = EasyDoc::load("input.docx")?;
// ... modify content.blocks ...
EasyDoc::write_content(&content, "output.docx")?;

// In-memory
let bytes = EasyDoc::write_content_to_bytes(&content)?;
# Ok::<(), easydoc::DocError>(())

6. EasyDoc API Reference

6.1 Write APIs

6.2 Read APIs

6.3 Markdown APIs

6.4 Semantic Model APIs

6.5 ViewMode (4 Modes)

7. Derive Macro

#[derive(DocxRow)] generates schema(), from_row(), to_row(), and their converter-aware variants automatically.

7.1 Struct-Level Attributes

7.2 Field-Level Attributes

7.3 Annotation to OOXML Mapping

8. Error Model

All operations return easydoc::Result<T> (alias for Result<T, DocError>).

9. Security & Resource Limits

10. Build, Test & Quality Gates

10.1 Basic Gates

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
cargo doc --workspace --all-features --no-deps

10.2 Test Matrix

11. Upstream Compatibility

easydoc-rust is the DOC/DOCX counterpart of easyexcel-rust, sharing the same architecture: fluent builder + derive macro + converter registry.

11.1 Compatibility Target

11.2 Object & Method Mapping

11.3 Language Semantic Mapping

12. Related Projects

• easyexcel-rust -- Excel counterpart (same architecture)
• Java: easy4j-easydoc (Apache POI + docx4j baseline)

13. License

Apache-2.0 -- see LICENSE for details.

Back to top · docs.rs · crates.io · Issues