Struct Document 

pub struct Document {

    pub blocks: Vec<Block>,
    pub header: Option<HeaderFooter>,
    pub footer: Option<HeaderFooter>,
    pub header_first: Option<HeaderFooter>,
    pub footer_first: Option<HeaderFooter>,
    pub header_even: Option<HeaderFooter>,
    pub footer_even: Option<HeaderFooter>,
    pub page_setup: PageSetup,
    pub styles: Vec<Style>,
    pub numbering_definitions: Vec<NumberingDefinition>,
    pub footnotes: Vec<Note>,
    pub endnotes: Vec<Note>,
    pub comments: Vec<Comment>,
    pub theme: Option<Theme>,
    pub track_changes: bool,
    pub properties: DocumentProperties,
    pub protection: Option<ProtectionKind>,
    pub extended_properties: ExtendedProperties,
    pub custom_properties: Vec<(String, CustomPropertyValue)>,
}

A .docx document: a sequence of block-level content (paragraphs and tables), in reading order, plus an optional default header/footer and a set of named styles (word/styles.xml) paragraphs/runs can refer to.

Fields

blocks: Vec<Block>

The blocks that make up the document body, in order.

header: Option<HeaderFooter>

The document’s default header (w:headerReference[@w:type='default']), shown on every page unless a page-specific header overrides it (header_first/ header_even, below).

footer: Option<HeaderFooter>

The document’s default footer, mirroring header.

header_first: Option<HeaderFooter>

A header shown only on the section’s first page (w:headerReference[@w:type='first']), overriding header for that one page. Setting this (or footer_first) automatically makes the writer emit w:sectPr/w:titlePg (CT_OnOff) — without it, Word ignores the first-type reference entirely and just repeats the default header, per ECMA-376.

footer_first: Option<HeaderFooter>

A footer shown only on the section’s first page, mirroring header_first.

header_even: Option<HeaderFooter>

A header shown only on even-numbered pages (w:headerReference[@w:type='even']) — header/header_first become the odd-page headers once this is set. Setting this (or footer_even) automatically makes the writer emit w:evenAndOddHeaders in word/settings.xml (CT_OnOff) — without it, Word ignores the even-type reference and just repeats the default/odd header on every page, per ECMA-376.

footer_even: Option<HeaderFooter>

A footer shown only on even-numbered pages, mirroring header_even.

page_setup: PageSetup

This document’s page setup — size, orientation, margins, columns (w:sectPr’s pgSz/pgMar/cols). Unlike header/footer, this is not optional: WordprocessingML always needs some page setup, so Default gives the exact fixed A4/standard-margins values this crate has always written since (PageSetup::default), preserving old behavior for callers who don’t set this. Only a single, document-wide page setup is modeled — WordprocessingML actually allows several independent page setups via mid-document section breaks (a new w:sectPr inside a paragraph’s own w:pPr), deliberately not modeled here: mid-document section breaks are a rare, advanced case, and supporting only a single document-wide page setup keeps the model considerably simpler without real demand yet for the alternative.

styles: Vec<Style>

Named styles declared for this document (word/styles.xml, CT_Styles’s style elements), referenced from paragraphs (Paragraph.style_id) and runs (Run.style_id) by id. Only written if non-empty — see writer.rs.

numbering_definitions: Vec<NumberingDefinition>

Numbering (list) definitions declared for this document (word/numbering.xml), referenced from paragraphs (Paragraph.numbering_id) by id. Only written if non-empty — see writer.rs.

footnotes: Vec<Note>

Footnotes declared for this document (word/footnotes.xml), referenced from the body by id (RunContent::NoteReference). Only written if non-empty — see writer.rs.

endnotes: Vec<Note>

Endnotes declared for this document (word/endnotes.xml), mirroring footnotes.

comments: Vec<Comment>

Comments declared for this document (word/comments.xml), anchored to a range of the body via Run.comment_ids — see Comment’s doc comment for how the underlying w:commentRangeStart/ w:commentRangeEnd/w:commentReference markers are derived from that field rather than modeled by hand. Only written if non-empty — see writer.rs.

theme: Option<Theme>

This document’s theme (word/theme/theme1.xml), or None to leave it unset entirely — a document with no theme part still opens fine in Word, just falling back to whatever theme Word’s own default template carries. Only written if Some — see writer.rs, and Theme’s own doc comment for what is/isn’t modeled.

track_changes: bool

Whether Word should track changes (insertions/deletions/formatting changes) made to this document from now on (w:trackRevisions — confirmed via ECMA-376’s own CT_Settings schema fragment and docx4j’s generated CTSettings binding; despite the UI calling the feature “Track Changes”, the underlying element is not named w:trackChanges, easy to get wrong — CT_OnOff, in word/settings.xml). This is only the simple on/off editing-mode toggle — matching the equivalent checkbox under Word’s Review > Track Changes menu — not a way to author individual tracked revisions (w:ins/w:del/w:rPrChange/..) programmatically; this crate exposes exactly this one on/off toggle and nothing more — no API here creates individual revision marks. false (the default) omits w:trackRevisions entirely, which is equivalent to explicitly disabling it.

properties: DocumentProperties

This document’s core properties (docProps/core.xml, CT_CoreProperties — title, author, subject, etc.). Left at its Default (every field None) writes the same near-empty <cp:coreProperties/> this crate has always written; setting any field populates just that element, since CT_CoreProperties is an xsd:all group (every child optional, no fixed order — confirmed via ECMA-376’s own schema fragment, unlike the many strict xsd:sequence groups this project has had to pin down elsewhere).

protection: Option<ProtectionKind>

This document’s editing-restriction protection (w:documentProtection, CT_DocProtect, in word/settings.xml), or None for no restriction. Only the no-password form is modeled (w:enforcement="1" with no w:cryptProviderType/hash/salt) — a password-protected variant involves a cryptographic hash of the password plus a random salt, real complexity with no proportionate demand seen yet in this project, matching the “simple case first” posture already applied elsewhere (e.g. Run.text_border’s fixed appearance instead of CT_Border’s full richness). See ProtectionKind for which restriction levels are modeled.

extended_properties: ExtendedProperties

This document’s extended properties (docProps/app.xml, CT_Properties — application-defined metadata, distinct from docProps/core.xml’s Dublin Core fields above). Only Company/Manager are modeled — see ExtendedProperties’s own doc comment for why the many statistical fields (Words/Pages/ Characters/..) aren’t. Left at its Default (both fields None), this crate still always writes docProps/app.xml with just Application set (unchanged from before this field existed) — see writer.rs’s to_extended_properties_xml.

custom_properties: Vec<(String, CustomPropertyValue)>

This document’s custom properties (docProps/custom.xml, CT_Properties — arbitrary user-defined name/value metadata pairs). A Vec of (name, value) pairs, not a map — order matters here: it determines the pid (property id) each entry gets when written (2, 3, 4. in declaration order; 0/1 are reserved by the format and never assigned), so insertion order is preserved rather than an arbitrary hash-map order. Only written if non-empty, same “optional part” convention as styles/footnotes/etc. See CustomPropertyValue for which value types are modeled.

Implementations

impl Document

pub fn new() -> Document

Creates an empty document.

Examples found in repository

examples/hello_world_docx.rs (line 16)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.docx");

    // `Document` and `Paragraph` both come from `office_toolkit::prelude`.
    let document = Document::new().with_paragraph(Paragraph::with_text("Hello, world!"));
    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .docx.
    let reopened = Document::open_file(&path)?;
    let text = reopened
        .paragraphs()
        .next()
        .map(|paragraph| paragraph.text());
    println!("Read back: {text:?}");

    Ok(())
}

examples/docx_images_and_charts.rs (line 28)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_images_and_charts.docx");
    let image_bytes = std::fs::read(image_fixture_path())?;

    // 2 inches wide, 1.5 inches tall (914,400 EMU per inch).
    let image = Image::new(image_bytes, ImageFormat::Png, 1_828_800, 1_371_600)
        .with_description("Project test image");
    let chart = EmbeddedChart::new(sample_chart_space(), 4_572_000, 2_743_200)
        .with_name("Quarterly revenue");

    let document = Document::new()
        .with_paragraph(heading("An inline image", false))
        .with_paragraph(Paragraph::new().with_run(Run::with_image(image)))
        .with_paragraph(heading("An embedded bar chart", true))
        .with_paragraph(Paragraph::new().with_run(Run::with_chart(chart)));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/docx_theme.rs (line 15)

fn main() -> office_toolkit::Result<()> {
    let default_theme_document = Document::new()
        .with_theme(Theme::office_default())
        .with_paragraph(Paragraph::with_text("Office's built-in default theme."))
        .with_paragraph(Paragraph::with_text(
            "Cambria for headings, Calibri for body text, the classic Office palette.",
        ));
    let default_path = output_path("docx_theme_default.docx");
    default_theme_document.save_to_file(&default_path)?;
    println!("Wrote {}", default_path.display());

    // A custom, branded theme: a dark navy/orange palette and a different
    // heading/body font pairing.
    let custom_colors = ColorScheme::new(
        "1B1B1B", "FFFFFF", "0A2540", "F5F5F5", "0A2540", "E8622C", "2E86AB", "6FB98F", "F4A259",
        "8E4585", "1155CC", "6B3FA0",
    );
    let custom_fonts = FontScheme::new("Georgia", "Verdana");
    let custom_theme_document = Document::new()
        .with_theme(Theme::new("Custom Brand", custom_colors, custom_fonts))
        .with_paragraph(Paragraph::with_text("A custom, branded theme."))
        .with_paragraph(Paragraph::with_text(
            "Georgia for headings, Verdana for body text, a navy/orange palette.",
        ));
    let custom_path = output_path("docx_theme_custom.docx");
    custom_theme_document.save_to_file(&custom_path)?;
    println!("Wrote {}", custom_path.display());

    Ok(())
}

examples/docx_metadata_and_protection.rs (line 29)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

examples/docx_page_layout.rs (line 34)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/docx_styles_and_lists.rs (line 33)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

Additional examples can be found in:

• examples/docx_tables.rs
• examples/docx_navigation_and_annotations.rs
• examples/docx_text_formatting.rs

pub fn with_paragraph(self, paragraph: Paragraph) -> Document

Appends a paragraph block and returns the document for chaining.

Examples found in repository

examples/hello_world_docx.rs (line 16)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.docx");

    // `Document` and `Paragraph` both come from `office_toolkit::prelude`.
    let document = Document::new().with_paragraph(Paragraph::with_text("Hello, world!"));
    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .docx.
    let reopened = Document::open_file(&path)?;
    let text = reopened
        .paragraphs()
        .next()
        .map(|paragraph| paragraph.text());
    println!("Read back: {text:?}");

    Ok(())
}

examples/docx_images_and_charts.rs (line 29)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_images_and_charts.docx");
    let image_bytes = std::fs::read(image_fixture_path())?;

    // 2 inches wide, 1.5 inches tall (914,400 EMU per inch).
    let image = Image::new(image_bytes, ImageFormat::Png, 1_828_800, 1_371_600)
        .with_description("Project test image");
    let chart = EmbeddedChart::new(sample_chart_space(), 4_572_000, 2_743_200)
        .with_name("Quarterly revenue");

    let document = Document::new()
        .with_paragraph(heading("An inline image", false))
        .with_paragraph(Paragraph::new().with_run(Run::with_image(image)))
        .with_paragraph(heading("An embedded bar chart", true))
        .with_paragraph(Paragraph::new().with_run(Run::with_chart(chart)));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/docx_theme.rs (line 17)

fn main() -> office_toolkit::Result<()> {
    let default_theme_document = Document::new()
        .with_theme(Theme::office_default())
        .with_paragraph(Paragraph::with_text("Office's built-in default theme."))
        .with_paragraph(Paragraph::with_text(
            "Cambria for headings, Calibri for body text, the classic Office palette.",
        ));
    let default_path = output_path("docx_theme_default.docx");
    default_theme_document.save_to_file(&default_path)?;
    println!("Wrote {}", default_path.display());

    // A custom, branded theme: a dark navy/orange palette and a different
    // heading/body font pairing.
    let custom_colors = ColorScheme::new(
        "1B1B1B", "FFFFFF", "0A2540", "F5F5F5", "0A2540", "E8622C", "2E86AB", "6FB98F", "F4A259",
        "8E4585", "1155CC", "6B3FA0",
    );
    let custom_fonts = FontScheme::new("Georgia", "Verdana");
    let custom_theme_document = Document::new()
        .with_theme(Theme::new("Custom Brand", custom_colors, custom_fonts))
        .with_paragraph(Paragraph::with_text("A custom, branded theme."))
        .with_paragraph(Paragraph::with_text(
            "Georgia for headings, Verdana for body text, a navy/orange palette.",
        ));
    let custom_path = output_path("docx_theme_custom.docx");
    custom_theme_document.save_to_file(&custom_path)?;
    println!("Wrote {}", custom_path.display());

    Ok(())
}

examples/docx_metadata_and_protection.rs (lines 37-40)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

examples/docx_page_layout.rs (line 40)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/docx_styles_and_lists.rs (line 39)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

Additional examples can be found in:

• examples/docx_tables.rs
• examples/docx_navigation_and_annotations.rs
• examples/docx_text_formatting.rs

pub fn with_table(self, table: Table) -> Document

Appends a table block and returns the document for chaining.

Examples found in repository

examples/docx_tables.rs (line 75)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_tables.docx");

    let plain_table = Table::new()
        .with_row(
            TableRow::new()
                .with_cell(TableCell::with_text("Name"))
                .with_cell(TableCell::with_text("Score")),
        )
        .with_row(
            TableRow::new()
                .with_cell(TableCell::with_text("Alice"))
                .with_cell(TableCell::with_text("92")),
        )
        .with_row(
            TableRow::new()
                .with_cell(TableCell::with_text("Bob"))
                .with_cell(TableCell::with_text("87")),
        );

    let merged_table = Table::new()
        .with_row(
            TableRow::new()
                .with_repeat_as_header_row(true)
                .with_cell(TableCell::with_text("Quarterly report").with_horizontal_span(3)),
        )
        .with_row(
            TableRow::new()
                .with_cell(
                    TableCell::with_text("Region").with_vertical_merge(VerticalMerge::Restart),
                )
                .with_cell(TableCell::with_text("Q1"))
                .with_cell(TableCell::with_text("Q2")),
        )
        .with_row(
            TableRow::new()
                .with_cell(TableCell::new().with_vertical_merge(VerticalMerge::Continue))
                .with_cell(TableCell::with_text("1,200"))
                .with_cell(TableCell::with_text("1,350")),
        );

    let styled_table = Table::new()
        .with_column_widths(vec![3_000, 3_000, 3_000])
        .with_border_color("2E74B5")
        .with_indent_twips(360)
        .with_row(
            TableRow::new()
                .with_height_twips(500)
                .with_cell(TableCell::with_text("Header A").with_shading_color("D9E2F3"))
                .with_cell(TableCell::with_text("Header B").with_shading_color("D9E2F3"))
                .with_cell(TableCell::with_text("Header C").with_shading_color("D9E2F3")),
        )
        .with_row(
            TableRow::new()
                .with_cant_split(true)
                .with_cell(TableCell::with_text("1").with_border(true))
                .with_cell(TableCell::with_text("2").with_border(true))
                .with_cell(TableCell::with_text("3").with_border(true)),
        );

    let document = Document::new()
        .with_paragraph(heading("A plain table", false))
        .with_table(plain_table)
        .with_paragraph(heading(
            "Merged cells: a spanning header row and a vertically merged column",
            true,
        ))
        .with_table(merged_table)
        .with_paragraph(heading(
            "Column widths, border color, shading and indentation",
            true,
        ))
        .with_table(styled_table);

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn add_paragraph(&mut self, text: impl Into<String>) -> &mut Paragraph

Appends a paragraph with the given text and returns a mutable reference to it, for further in-place styling (e.g. document.add_paragraph("..").with_alignment(..) isn’t possible since with_* consumes self — reach for paragraph.alignment =.. or paragraph.runs.push(..) on the returned reference instead). A &mut self counterpart to Self::with_paragraph, for the common case of building a document by appending to it in a loop, where the consuming builder would otherwise force a document = document.with_paragraph(..) reassignment on every iteration.

pub fn paragraphs(&self) -> impl Iterator<Item = &Paragraph>

Iterates over the document’s paragraphs only, skipping tables. A convenience for the common case of not caring about tables; use blocks directly to see paragraphs and tables in their actual reading order.

Examples found in repository

examples/hello_world_docx.rs (line 23)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.docx");

    // `Document` and `Paragraph` both come from `office_toolkit::prelude`.
    let document = Document::new().with_paragraph(Paragraph::with_text("Hello, world!"));
    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .docx.
    let reopened = Document::open_file(&path)?;
    let text = reopened
        .paragraphs()
        .next()
        .map(|paragraph| paragraph.text());
    println!("Read back: {text:?}");

    Ok(())
}

pub fn tables(&self) -> impl Iterator<Item = &Table>

Iterates over the document’s tables only, skipping paragraphs.

pub fn with_header(self, header: HeaderFooter) -> Document

Sets the document’s default header and returns it for chaining.

Examples found in repository

examples/docx_page_layout.rs (line 36)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_footer(self, footer: HeaderFooter) -> Document

Sets the document’s default footer and returns it for chaining.

Examples found in repository

examples/docx_page_layout.rs (line 37)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_header_first(self, header: HeaderFooter) -> Document

Sets the document’s first-page header and returns it for chaining. See header_first’s doc comment.

Examples found in repository

examples/docx_page_layout.rs (line 38)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_footer_first(self, footer: HeaderFooter) -> Document

Sets the document’s first-page footer and returns it for chaining.

pub fn with_header_even(self, header: HeaderFooter) -> Document

Sets the document’s even-page header and returns it for chaining. See header_even’s doc comment.

Examples found in repository

examples/docx_page_layout.rs (line 39)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_footer_even(self, footer: HeaderFooter) -> Document

Sets the document’s even-page footer and returns it for chaining.

pub fn with_page_setup(self, page_setup: PageSetup) -> Document

Sets the document’s page setup and returns it for chaining.

Examples found in repository

examples/docx_page_layout.rs (line 35)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_style(self, style: Style) -> Document

Appends a named style declaration and returns the document for chaining.

Examples found in repository

examples/docx_styles_and_lists.rs (line 34)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_numbering_definition( self, definition: NumberingDefinition, ) -> Document

Appends a numbering (list) definition and returns the document for chaining.

Examples found in repository

examples/docx_styles_and_lists.rs (line 36)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_footnote(self, note: Note) -> Document

Appends a footnote declaration and returns the document for chaining.

Examples found in repository

examples/docx_navigation_and_annotations.rs (lines 63-66)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_endnote(self, note: Note) -> Document

Appends an endnote declaration and returns the document for chaining.

Examples found in repository

examples/docx_navigation_and_annotations.rs (lines 67-70)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_comment(self, comment: Comment) -> Document

Appends a comment declaration and returns the document for chaining.

Examples found in repository

examples/docx_navigation_and_annotations.rs (lines 51-55)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_structured_document_tag( self, sdt: StructuredDocumentTag, ) -> Document

Appends a structured document tag block and returns the document for chaining.

Examples found in repository

examples/docx_navigation_and_annotations.rs (lines 73-79)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_theme(self, theme: Theme) -> Document

Sets the document’s theme and returns it for chaining.

Examples found in repository

examples/docx_theme.rs (line 16)

fn main() -> office_toolkit::Result<()> {
    let default_theme_document = Document::new()
        .with_theme(Theme::office_default())
        .with_paragraph(Paragraph::with_text("Office's built-in default theme."))
        .with_paragraph(Paragraph::with_text(
            "Cambria for headings, Calibri for body text, the classic Office palette.",
        ));
    let default_path = output_path("docx_theme_default.docx");
    default_theme_document.save_to_file(&default_path)?;
    println!("Wrote {}", default_path.display());

    // A custom, branded theme: a dark navy/orange palette and a different
    // heading/body font pairing.
    let custom_colors = ColorScheme::new(
        "1B1B1B", "FFFFFF", "0A2540", "F5F5F5", "0A2540", "E8622C", "2E86AB", "6FB98F", "F4A259",
        "8E4585", "1155CC", "6B3FA0",
    );
    let custom_fonts = FontScheme::new("Georgia", "Verdana");
    let custom_theme_document = Document::new()
        .with_theme(Theme::new("Custom Brand", custom_colors, custom_fonts))
        .with_paragraph(Paragraph::with_text("A custom, branded theme."))
        .with_paragraph(Paragraph::with_text(
            "Georgia for headings, Verdana for body text, a navy/orange palette.",
        ));
    let custom_path = output_path("docx_theme_custom.docx");
    custom_theme_document.save_to_file(&custom_path)?;
    println!("Wrote {}", custom_path.display());

    Ok(())
}

pub fn with_track_changes(self, track_changes: bool) -> Document

Sets whether Word should track changes made to this document from now on and returns it for chaining. See track_changes’s doc comment.

Examples found in repository

examples/docx_metadata_and_protection.rs (line 36)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

pub fn with_properties(self, properties: DocumentProperties) -> Document

Sets the document’s core properties (title, author, etc.) and returns it for chaining. See DocumentProperties’s doc comment.

Examples found in repository

examples/docx_metadata_and_protection.rs (line 30)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

pub fn with_protection(self, protection: ProtectionKind) -> Document

Sets which editing restrictions are enforced on the document and returns it for chaining. See ProtectionKind’s doc comment.

Examples found in repository

examples/docx_metadata_and_protection.rs (line 46)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

pub fn with_extended_properties( self, extended_properties: ExtendedProperties, ) -> Document

Sets the document’s extended properties (company/manager) and returns it for chaining. See ExtendedProperties’s doc comment.

Examples found in repository

examples/docx_metadata_and_protection.rs (line 31)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

pub fn with_custom_property( self, name: impl Into<String>, value: CustomPropertyValue, ) -> Document

Appends a custom property (name/value pair) and returns the document for chaining. See custom_properties’s doc comment for why order matters here.

Examples found in repository

examples/docx_metadata_and_protection.rs (line 32)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

impl Document

pub fn read_from<R>(reader: R) -> Result<Document, Error>

where R: Read + Seek,

Reads a .docx package from a seekable byte source.

impl Document

pub fn write_to<W>(&self, writer: W) -> Result<W, Error>

where W: Write + Seek,

Writes this document out as a valid .docx package.

Writes [Content_Types].xml, _rels/.rels, word/document.xml, word/_rels/document.xml.rels, word/settings.xml, docProps/core.xml, docProps/app.xml, and — if set/non-empty — word/header1.xml/word/footer1.xml (default) plus header2.xml/footer2.xml (first page) and header3.xml/ footer3.xml (even pages), word/styles.xml, word/numbering.xml, word/footnotes.xml, word/endnotes.xml, word/comments.xml, word/theme/theme1.xml, docProps/custom.xml. webSettings.xml/ fontTable.xml are not written yet; they are optional, not required for the file to open cleanly. Page setup (size/orientation/margins/ columns) comes from Document.page_setup, a single document-wide section — see that field’s doc comment for why mid-document section breaks aren’t modeled.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Document

fn default() -> Document

Returns the “default value” for a type.

impl OpenFile for Document

Available on crate feature word only.

fn open_file(path: impl AsRef<Path>) -> Result<Self>

Reads self from the file at path.

impl PartialEq for Document

fn eq(&self, other: &Document) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl SaveToFile for Document

Available on crate feature word only.

fn save_to_file(&self, path: impl AsRef<Path>) -> Result<()>

Writes self to the file at path, creating it (or truncating an existing one) as needed.

impl StructuralPartialEq for Document