Introduction

docboss is a DOCX and DOC engine written from scratch in safe Rust against the specifications: ECMA-376 for Office Open XML WordprocessingML, and Microsoft's [MS-DOC], [MS-CFB], [MS-OLEPS], [MS-ODRAW] and [MS-OFFCRYPTO] for the Word 97-2003 binary format, its compound-file container and encryption. It has no C dependencies and no bindings to another engine: the ZIP container, the XML tokenizer, the compound-file reader, the font parsers, the layout engine and the rasterizer are its own. One core sits behind every surface: the docboss command-line tool, an interactive terminal explorer (docboss tui), a set of Rust library crates, and a native Python extension.

One model for two formats

A .docx file is a ZIP package of XML parts; a .doc file is a compound file holding a binary stream of text, a piece table and formatting records. Both readers produce the same document model (docboss-model): sections with their page setup, paragraphs and tables, runs with their properties, a style sheet that resolves effective formatting, list definitions that produce the document's own labels, footnotes, endnotes, comments, headers, footers, fields, bookmarks and media. Everything after reading (text, Markdown, HTML, JSON, layout, rendering, DOCX writing) works on that model, so it behaves the same for both formats. The format is detected from the leading bytes, never from the file name.

Leniency

Real-world files are damaged: truncated downloads, archivers that write a bad central directory, converters that break FAT chains or leave dangling relationships. docboss reads them anyway:

• A ZIP with a missing or broken central directory is read from its local headers; a damaged deflate stream keeps what inflated before the damage.
• A compound file with a looping or truncated sector chain is followed as far as it goes.
• XML that is not well formed still yields balanced elements.

Leniency never hides what it cost. Every approximated or dropped item is a Diagnostic on the document: docboss diagnostics lists them, and the libraries expose them as a value. An empty list means the reader took the file as written.

Scope

docboss reads, lays out, renders and writes word-processing documents. It does not edit a document in place and does not run macros. The limitations page lists what is missing, and the conformance ledger records the status of every clause of the standards it reads.

Installation

Python

pip install docboss

Wheels are abi3 builds for CPython 3.12 and later, so one wheel covers every later Python version. No Rust toolchain is needed to install one.

Command-line tool

cargo install docboss-cli

This builds the docboss binary from crates.io with a stable Rust toolchain. From a checkout, make install does the same for the working tree.

Rust crates

Add the crates you need:

cargo add docboss-core docboss-output docboss-layout docboss-render docboss-write
cargo add docboss-aio --features http   # async and remote reads

docboss-core re-exports the document model, so most programs start from docboss_core::open.

Fonts for rendering

Rendering uses the fonts installed on the machine: the macOS, Linux and Windows font directories, LibreOffice's bundled fonts, and any directory named in DOCBOSS_FONT_PATH (:-separated). Fonts embedded in a DOCX are used first. When a document names a font that is not installed, a metric-compatible substitute is used where one exists (Carlito for Calibri, Caladea for Cambria, Liberation Sans or Arimo for Arial and Helvetica, Liberation Serif or Tinos for Times New Roman, Liberation Mono or Cousine for Courier New), so line breaks and page counts stay close to Word's. docboss fonts report.docx shows what each font resolved to.

Coding agents

docboss skill install writes a skill document into ./.claude/skills/docboss, or into ~/.claude/skills/docboss with --global, so coding agents know the CLI and the Python API. docboss skill print writes it to stdout.

Quickstart

One taste of each surface. report.docx and legacy.doc stand in for any Word documents of yours; Installation covers getting the binary, the wheel and the crates.

CLI

docboss info   report.docx                   # format, metadata, page setup, page count, counts
docboss text   report.docx                   # plain text with list labels
docboss text   legacy.doc                    # Word 97-2003 files read the same way
docboss md     report.docx                   # GitHub-flavored Markdown
docboss render report.docx --page 1 -o page.png --scale 2
docboss images report.docx -o images         # the document's pictures, as stored
docboss convert legacy.doc -o legacy.docx    # DOC to a fresh DOCX
docboss create md notes.md -o notes.docx     # Markdown composed into a DOCX

render prints each file it wrote; images writes into the directory it is given and creates it when missing. Page numbers are 1-based on the command line.

Python

from pathlib import Path

import docboss

doc = docboss.Document("report.docx")
print(doc.format, doc.page_count(), "pages")

text = doc.extract_text()           # one line per paragraph, list labels included
markdown = doc.extract_markdown()   # headings, lists, tables, footnotes, links

Path("page.png").write_bytes(doc.render(0, scale=2.0))

for image in doc.images():
    print(image.name, image.content_type, len(image.data))

legacy = docboss.Document("legacy.doc")
Path("legacy.docx").write_bytes(legacy.to_docx())

docx = docboss.md.to_docx(Path("notes.md").read_text())

Document also opens from memory (Document(data=raw_bytes)), pages index 0-based with negative indexes from the end, and render returns PNG bytes unless format= says otherwise.

Rust

With docboss-core, docboss-output, docboss-layout and docboss-render added:

use docboss_output::{to_markdown, MarkdownOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = docboss_core::open("report.docx")?;
    println!("{}", to_markdown(&doc, &MarkdownOptions::default()));

    let layout = docboss_layout::layout_document(&doc);
    docboss_render::render_page(&layout, 0, 2.0)?.save("page.png")?;
    Ok(())
}

Extracting text

docboss text report.docx
docboss text report.docx --headers-footers --comments
docboss text legacy.doc --no-labels -o legacy.txt

Plain text has one line per paragraph. List paragraphs start with the label the document's numbering gives them (1., a), •), computed from the list definitions, their start values and overrides, the way Word numbers them. Table rows become one line each with tab-separated cells. Footnote and endnote references become [1] and [i], and the notes' text follows the main text; --no-notes leaves both out. --headers-footers writes each section's headers before it and its footers after it, and --comments marks comment anchors [c1] and appends the comments with their authors.

What is left out, as ECMA-376 and [MS-DOC] define it: hidden text (vanish), deleted revisions (inserted ones are kept), and field instructions; a field contributes its cached result, so a table of contents or a PAGE field reads as the file shows it. Text boxes are part of the text, written after the paragraph that anchors them.

import docboss

doc = docboss.Document("report.docx")
text = doc.extract_text(headers_footers=True, notes=True, comments=False, list_labels=True)

Many files at once

import docboss

texts = docboss.extract_texts(["report.docx", "legacy.doc"], threads=8)
lenient = docboss.extract_texts(["report.docx", "not-a-document.txt"], strict=False)
print(lenient[1])   # None: that file failed, the others still came back

extract_texts reads every file on a Rust thread pool in one call, without the GIL, and returns the texts in input order. With strict=True (the default) the first failure raises DocbossError; with strict=False a failed file gives None. It is the fastest way to feed a pipeline.

Blocks

For retrieval pipelines, the block view keeps each paragraph's role:

docboss json report.docx --blocks

import docboss

for block in docboss.Document("report.docx").blocks():
    print(block.kind, block.heading_level, block.list_label, block.text)

kind is paragraph, heading, list_item or table; headings come from outline levels and heading styles, list items carry their level and label. Empty paragraphs are left out.

Markdown, HTML and JSON

Markdown

docboss md report.docx
docboss md report.docx --images images -o report.md   # export images and link them
docboss md report.docx --embed-images                 # data: URIs instead
docboss md report.docx --title --page-breaks

The Markdown is GitHub-flavored:

• Headings come from the paragraph's outline level or a Heading N or Title style.
• Bold, italic and strikethrough spans are merged across adjacent runs, with whitespace kept outside the markers. A paragraph set entirely in a monospace font, or in a code style, becomes a fenced code block.
• Lists nest by numbering level; bullets become -, numbered items 1..
• Tables become pipe tables; merged cells, nested tables and multi-paragraph cells are flattened with <br>.
• Footnotes and endnotes become [^1] references with definitions at the end; hyperlinks and HYPERLINK fields become links.
• Images become ![description](name); --images DIR writes the files and links them there.

import docboss

doc = docboss.Document("report.docx")
markdown = doc.extract_markdown(images="reference", image_prefix="images/")
inline = doc.extract_markdown(images="embed")
bare = doc.extract_markdown(images="omit", title=True, page_breaks=True)

HTML

docboss html report.docx --standalone -o report.html
docboss html report.docx --images images -o fragment.html

HTML output is semantic: h1 to h6, p, strong, em, u, s, sup, sub, ul and ol with start attributes, tables with colspan and rowspan from merged cells, links, images and a footnotes section. Without --standalone it is a body fragment. Images are embedded as data: URIs unless --images exports them.

import docboss

html = docboss.Document("report.docx").extract_html(standalone=True)

JSON

docboss json report.docx            # the whole document model
docboss json report.docx --blocks   # one object per block
docboss q report.docx '.sections | length'
docboss q report.docx --blocks -r '.[] | select(.kind == "heading") | .text'

docboss q runs a jq program (through jaq) over the same JSON, so the model can be queried without writing code. In Python, Document.to_json(pretty=True) returns the model as a string.

Rendering pages

docboss render report.docx --page 1 -o page.png            # one page, 72 dpi
docboss render report.docx --scale 2 -o 'page-%d.png'      # every page at 144 dpi
docboss render report.docx --page 1 -o page.jpg --jpeg-quality 85
docboss render legacy.doc -o 'legacy-%d.ppm'

The -o extension picks the format: .png, .ppm, .bmp or .jpg/.jpeg. %d in the path is replaced by the page number; without --page every page is rendered, laid out once and painted on all cores. --scale is pixels per point, so 1.0 is 72 dpi and 2.0 is 144 dpi.

What layout does

docboss lays a document out the way Word does rather than the way a browser would:

• Paragraph and run properties are resolved through document defaults, the style chain, table styles, list levels and direct formatting.
• Lines break at Unicode line-break opportunities with soft hyphens honored, and are aligned or justified; line spacing follows the paragraph's rule (auto, exact, at least) with Word's extra leading on single spacing.
• Tab stops, leaders and default tabs; list labels with their hanging indents.
• Keep with next, keep lines together, widow and orphan control, page breaks before.
• Tables: grid widths, merged cells in both directions, cell margins, borders and shading, rows split across pages, header rows repeated on each page.
• Sections with their own page size, margins and columns; headers and footers for first, even and default pages, with PAGE and NUMPAGES fields in the section's number format.
• Footnotes at the bottom of the page they are referenced on; inline and floating images.

Fonts come from the machine and from the document; see Installation for where docboss looks and which substitutes it uses. docboss fonts report.docx prints each font the document names and the face it resolved to.

Python

from pathlib import Path

import docboss

doc = docboss.Document("report.docx")
print(doc.page_count(), "pages")
Path("first.png").write_bytes(doc.render(0, scale=2.0))
Path("last.jpg").write_bytes(doc.render(-1, format="jpeg", jpeg_quality=85))
for index, png in enumerate(doc.render_pages(scale=1.5)):
    Path(f"page-{index + 1}.png").write_bytes(png)

render_pages renders every page (or the indexes given in pages=) in parallel and returns the encoded images in page order. Layout is computed once per document and cached, so rendering pages one by one costs no second layout.

Rust

use docboss_render::Format;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = docboss_core::open("report.docx")?;
    let layout = docboss_layout::layout_document(&doc);
    for (index, page) in docboss_render::render_pages(&layout, 2.0).into_iter().enumerate() {
        std::fs::write(format!("page-{}.png", index + 1), page?.encode(Format::Png)?)?;
    }
    Ok(())
}

docboss_layout::layout takes an explicit FontDatabase when several documents should share one; layout_document builds one for the document, including its embedded fonts. Each laid-out page holds positioned glyph runs, rectangles, lines and images in points, so a program can inspect geometry without rasterizing.

What is not drawn

Text boxes, shapes with their preset and custom geometry, groups, canvases, gradient fills, SmartArt (from its saved drawing), charts (from their cached values), Office Math, WMF and EMF pictures and page borders are drawn, and body text wraps around floating images, text frames and floating tables (square, tight, through and top and bottom); text in table cells, text frames, headers and footers does not wrap around the floats there. Picture and pattern fills and shape effects are not drawn, 3-D, radar, stock, surface, bubble and bar-of-pie charts show an empty frame, and TIFF pictures draw a placeholder rectangle; docboss diagnostics report.docx --layout reports them and everything else layout approximated.

Extracting images

docboss images report.docx -o images
docboss images legacy.doc -o images

images writes every picture the document carries at its stored size and in its stored format (PNG, JPEG, GIF, BMP, EMF, WMF, TIFF), named after its part (image1.png). DOC pictures come from the Data stream and the OfficeArt BLIP store; DIB pictures are written as BMP, and identical DOC pictures are stored once.

from pathlib import Path

import docboss

for image in docboss.Document("report.docx").images():
    Path(image.file_name).write_bytes(image.data)
    print(image.name, image.content_type)

name is the part name inside the package (word/media/image1.png), file_name its last segment, and content_type is detected from the bytes. The Markdown and HTML writers reference or embed the same images (see Markdown, HTML and JSON).

Writing DOCX

docboss writes WordprocessingML packages from its document model. Output is deterministic: the same input produces identical bytes, ZIP entries carry a fixed timestamp, and dates appear only when the metadata states them.

Converting

docboss convert legacy.doc -o legacy.docx      # DOC to DOCX
docboss convert report.docx -o fresh.docx      # a fresh package from the model
docboss convert legacy.doc -o legacy.md        # or .html, .txt, .json by extension

import docboss

docboss.Document("legacy.doc").save_docx("legacy.docx")
data = docboss.Document("report.docx").to_docx()

A converted file carries what the model holds: text, styles, lists, tables, sections with headers and footers, notes, comments, fields, bookmarks, revisions and images. Embedded fonts and the theme part are not written.

Markdown to DOCX

docboss create md notes.md -o notes.docx --size a4 --title "Notes"

import docboss

docx = docboss.md.to_docx("# Notes\n\n- one\n- two\n\n| a | b |\n|---|---|\n| 1 | 2 |\n")

CommonMark and GFM map onto Word's built-in vocabulary: headings to Heading1 through Heading6, emphasis, strong and strikethrough to run properties, inline code and code blocks to monospace styles, links to hyperlinks, ordered, bullet, nested and task lists to numbering definitions, tables to tables with a header row, block quotes to the Quote style, thematic breaks to a bottom border, footnotes to footnotes. Relative image paths are read from the Markdown file's directory on the CLI, and from images_dir= in Python; without it an image becomes its alt text.

Composing from Rust

use docboss_write::{DocumentBuilder, ListKind, Para, TableBuilder};

let mut doc = DocumentBuilder::new();
doc.title("Q3 Report").heading(1, "Summary");
doc.paragraph(Para::new().text("Revenue grew ").bold("12%").text("."));
doc.items(ListKind::Bullet, &["North", "South"]);
let width = doc.text_width();
doc.block(TableBuilder::new(2, width).header(&["Region", "Growth"]).row(&["North", "14%"]));
let bytes = doc.to_bytes()?;
assert!(bytes.starts_with(b"PK"));
Ok::<(), docboss_write::Error>(())

DocumentBuilder covers metadata, page size and margins, styles, headings, paragraphs, lists, tables, images, footnotes, headers, footers and sections; docboss_write::to_bytes and save serialize any docboss_model::Document, and docboss_write::markdown::to_docx is the Markdown path.

Encrypted documents

Every read command takes --password, and Document takes password=:

docboss text locked.docx --password secret
docboss convert locked.docx --password secret -o unlocked.docx

import docboss

doc = docboss.Document("locked.docx", password="secret")
print(doc.extract_text())

What opens:

• DOCX protected with a password to open is an OLE compound file holding EncryptionInfo and EncryptedPackage streams ([MS-OFFCRYPTO]). docboss decrypts Agile encryption (AES-128 or AES-256 in CBC mode, SHA-1 or SHA-512 key derivation with the spin count, the data-integrity HMAC checked) and Standard encryption (AES-128 in ECB mode, SHA-1), then reads the package like any other. Word 2007 to 2013 and LibreOffice files open.
• DOC with RC4 or RC4 CryptoAPI encryption ([MS-DOC] with the [MS-OFFCRYPTO] key derivations), or with XOR obfuscation (the password verifier and XOR array of [MS-OFFCRYPTO] method 2; the password is tried in the document's code page and by the low byte of each character, as the specification asks).

A wrong password is an error that says so; a tampered Agile package fails its integrity check. Password-protected Word 6 and Word 95 files are refused with an error.

convert writes the decrypted document as a plain, unencrypted DOCX; there is no way to write an encrypted one yet.

Remote documents over HTTP

Every read command accepts an http(s):// URL:

docboss text https://example.com/report.docx
docboss info https://example.com/legacy.doc

The file is not downloaded whole. For a DOCX, docboss fetches the end of the file to find the ZIP central directory, then only the entries the reader needs: content types, relationships, document.xml, styles, numbering, notes and comments. Images are fetched only when a command needs them. For a DOC, it fetches the compound-file header, the FAT and directory sectors, and then only the sectors of the Word streams. Requests are coalesced and cached, so no byte is fetched twice; a server that ignores Range costs one full download. On a terminal, a line of coverage shows which parts of the file were fetched.

On Apache POI's saut_page.docx (2.96 MB, mostly images), extracting the text fetched 17.9 KB in 3 requests; a DOC reads its Data stream too, so it saves less.

Rust

docboss-aio with the http feature:

use docboss_aio::{AsyncDocument, ReadOptions};
use docboss_output::{to_text, TextOptions};

async fn run() -> docboss_aio::Result<()> {
let remote = AsyncDocument::open_url("https://example.com/report.docx").await?;
let doc = remote.read(&ReadOptions::default()).await?;
println!("{}", to_text(&doc, &TextOptions::default()));
println!("{} of {} bytes in {} requests", remote.bytes_fetched(), remote.len(), remote.requests().len());
Ok(()) }

ReadOptions { media: true, .. } fetches images too; otherwise AsyncDocument::load_media fetches them later. AsyncDocument::open and from_bytes give the same interface over local files and memory, and from_backend over any byte source that implements Backend.

Python

import asyncio

import docboss

async def main() -> None:
    doc = await docboss.AsyncDocument.open_url("https://example.com/report.docx")
    print(doc.format, doc.part_names()[:3])
    text = await doc.extract_text()
    markdown = await doc.extract_markdown(images="omit")
    styles = await doc.part("word/styles.xml")
    print(doc.bytes_fetched, "bytes in", len(doc.requests), "requests")

asyncio.run(main())

AsyncDocument.open(path), from_bytes(data) and open_url(url) are coroutines and take password=. The extraction methods mirror Document's and are awaitable: extract_text, extract_markdown, extract_html, to_json, blocks, images, and part(name) for one ZIP entry or stream. bytes_fetched and requests report what was read so far, and await doc.document() returns a synchronous Document for rendering, DOCX writing and the rest of its API; images are fetched when a call needs them.

Exploring document internals

Containers

docboss parts report.docx                        # ZIP entries with stored and unpacked sizes
docboss parts legacy.doc                         # compound-file streams
docboss xml report.docx word/styles.xml          # one XML part, indented (--raw as stored)
docboss hex legacy.doc WordDocument --length 64  # hexdump of a part
docboss hex legacy.doc SummaryInformation        # control characters in names are optional

Compound-file stream names that start with a control character print as \x05SummaryInformation and can be addressed that way, without the prefix, or case-insensitively.

The model

docboss json report.docx | head
docboss q report.docx '.styles.styles | map(.id)'
docboss fonts report.docx
docboss diagnostics report.docx
docboss diagnostics report.docx --layout

diagnostics lists everything the reader approximated or dropped, with the part or stream it came from; --layout adds what layout approximated, such as fonts that fell back or pictures drawn as placeholders.

The terminal explorer

docboss tui report.docx

The explorer has a tree of the document (sections, paragraphs, tables and runs, plus headers and footers, notes, comments, styles, numbering, media, fonts, the container and diagnostics), an inspector with each node's direct and resolved properties and its style chain, an XML view of the selected part, a Markdown view, a page preview drawn with half-block characters, and a hex pane.

It needs an interactive terminal and exits with an error otherwise.

docboss CLI reference

Generated from docboss --help and each command's --help. Every command that reads a document detects DOCX or DOC from the bytes and accepts --password; where the help says so, it also takes an http(s):// URL, read with range requests. Errors go to stderr prefixed docboss:; document and I/O errors exit 1, usage errors and invalid jq programs exit 2.

DOCX and DOC parsing, extraction, rendering and conversion

Usage: docboss <COMMAND>

Commands:
  info         Format, metadata, page setup, page count and content counts
  text         Extract plain text
  md           Convert to GitHub-flavored Markdown
  html         Convert to semantic HTML; images are embedded unless --images is given
  json         Dump the document model as JSON
  q            Run a jq program over the JSON form of the document
  render       Lay out and render pages to PNG, PPM, BMP or JPEG (picked by the -o extension)
  images       Export the document's images at their stored size and format
  parts        List the ZIP entries or compound file streams of the container
  hex          Hexdump the whole file or one part of it
  xml          Print an XML part of a DOCX, indented
  convert      Convert to a fresh DOCX, or to .md, .html, .txt or .json, by the -o extension
  create       Create a new DOCX
  fonts        The fonts the document names and the faces they resolve to here
  diagnostics  Everything the lenient reader approximated or dropped
  skill        Install or print the skill document for coding agents
  tui          Explore the document interactively in the terminal
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

docboss info

Format, metadata, page setup, page count and content counts

Usage: docboss info [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
  -h, --help                 Print help

docboss text

Extract plain text

Usage: docboss text [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
      --headers-footers      Include each section's headers and footers
      --no-notes             Leave out footnotes and endnotes
      --comments             Include comments
      --no-labels            Leave list labels (1., a), bullets) out
  -o, --out <OUT>            Write to a file instead of stdout
  -h, --help                 Print help

docboss md

Convert to GitHub-flavored Markdown

Usage: docboss md [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
      --headers-footers      Include each section's headers and footers
      --no-notes             Leave out footnotes and endnotes
      --comments             Include comments
      --images <IMAGES>      Export images into this directory and link them from the Markdown
      --embed-images         Embed images as data: URIs
      --title                Start with the metadata title as a level-one heading
      --page-breaks          Write page breaks as thematic breaks (---)
  -o, --out <OUT>            Write to a file instead of stdout
  -h, --help                 Print help

docboss html

Convert to semantic HTML; images are embedded unless --images is given

Usage: docboss html [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
      --headers-footers      Include each section's headers and footers
      --no-notes             Leave out footnotes and endnotes
      --comments             Include comments
      --standalone           Write a whole HTML document instead of a body fragment
      --images <IMAGES>      Export images into this directory and link them instead of embedding
  -o, --out <OUT>            Write to a file instead of stdout
  -h, --help                 Print help

docboss json

Dump the document model as JSON

Usage: docboss json [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
      --blocks               The compact per-block view: type, style, heading level, list label, text
      --compact              One line instead of indented output
  -o, --out <OUT>            Write to a file instead of stdout
  -h, --help                 Print help

docboss q

Run a jq program over the JSON form of the document

Usage: docboss q [OPTIONS] <FILE> <PROGRAM>

Arguments:
  <FILE>     Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests
  <PROGRAM>  The jq program, e.g. '.metadata.title' or '.sections[].blocks | length'

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
  -r, --raw                  Print strings without quotes
      --blocks               Query the compact per-block view instead of the full model
  -h, --help                 Print help

docboss render

Lay out and render pages to PNG, PPM, BMP or JPEG (picked by the -o extension)

Usage: docboss render [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>          Password for an encrypted DOC or DOCX
      --page <PAGE>                  Page number (1-based); every page when omitted
      --scale <SCALE>                Pixels per point: 1.0 is 72 dpi [default: 1]
  -o, --out <OUT>                    Output path; %d is replaced by the page number [default: page-%d.png]
      --jpeg-quality <JPEG_QUALITY>  JPEG quality, 1 to 100
  -h, --help                         Print help

docboss images

Export the document's images at their stored size and format

Usage: docboss images [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
  -o, --out <OUT>            Output directory [default: .]
  -h, --help                 Print help

docboss parts

List the ZIP entries or compound file streams of the container

Usage: docboss parts <FILE>

Arguments:
  <FILE>  Path to the .docx or .doc file

Options:
  -h, --help  Print help

docboss hex

Hexdump the whole file or one part of it

Usage: docboss hex [OPTIONS] <FILE> [PART]

Arguments:
  <FILE>  Path to the .docx or .doc file
  [PART]  A ZIP entry (word/document.xml) or compound file stream (1Table)

Options:
      --offset <OFFSET>  First byte to dump [default: 0]
      --length <LENGTH>  Number of bytes to dump; to the end when omitted
      --width <WIDTH>    Bytes per row [default: 16]
  -h, --help             Print help

docboss xml

Print an XML part of a DOCX, indented

Usage: docboss xml [OPTIONS] <FILE> [PART]

Arguments:
  <FILE>  Path to the .docx file
  [PART]  The part, e.g. word/document.xml [default: word/document.xml]

Options:
      --raw   Print the part as stored, without re-indenting
  -h, --help  Print help

docboss convert

Convert to a fresh DOCX, or to .md, .html, .txt or .json, by the -o extension

Usage: docboss convert [OPTIONS] --out <OUT> <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
  -o, --out <OUT>            Output path
  -h, --help                 Print help

docboss create md

Compose CommonMark + GFM Markdown into a DOCX

Usage: docboss create md [OPTIONS] --out <OUT> <FILE>

Arguments:
  <FILE>  The Markdown file; relative image paths resolve against its directory

Options:
  -o, --out <OUT>      Output DOCX path
      --size <SIZE>    Page size [default: letter] [possible values: letter, a4]
      --title <TITLE>  Document title; the first heading's text by default
  -h, --help           Print help

docboss fonts

The fonts the document names and the faces they resolve to here

Usage: docboss fonts [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
  -h, --help                 Print help

docboss diagnostics

Everything the lenient reader approximated or dropped

Usage: docboss diagnostics [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
      --layout               Also lay the document out and report what layout approximated
  -h, --help                 Print help

docboss tui

Explore the document interactively in the terminal

Usage: docboss tui [OPTIONS] <FILE>

Arguments:
  <FILE>  Path or http(s):// URL of the .docx or .doc file; the format is detected from its bytes. A URL is read with range requests

Options:
      --password <PASSWORD>  Password for an encrypted DOC or DOCX
  -h, --help                 Print help

docboss skill install

Install the skill for coding agents: into ./.claude/skills/docboss (this project), or with --global into ~/.claude/skills/docboss

Usage: docboss skill install [OPTIONS]

Options:
  -g, --global  Install into ~/.claude/skills instead of ./.claude/skills
  -h, --help    Print help

docboss skill print

Print the skill document to stdout

Usage: docboss skill print

Options:
  -h, --help  Print help

Python API reference

import docboss exposes the classes and functions below; docboss.md holds the Markdown-to-DOCX function. Type stubs ship with the package (_docboss.pyi, py.typed).

docboss.Document

Document(path=None, *, data=None, password=None)

Opens a DOCX or DOC file from a path, or from data (bytes, bytearray or memoryview); exactly one of the two must be given, otherwise TypeError. The format is detected from the bytes. password opens an encrypted DOCX or DOC. Bad input, a missing or wrong password, and unsupported formats raise DocbossError. Documents are immutable and can be used from any thread; heavy calls release the GIL.

images in the Markdown and HTML methods is "reference" (link to image_prefix plus the image's file name), "embed" (data: URIs) or "omit".

Layout runs once per document and is cached; documents without embedded fonts share one font database for the process.

docboss.AsyncDocument

The asynchronous reader, over files, bytes or http(s):// URLs, fetching only the byte ranges each call needs.

Functions

Exceptions

docboss.DocbossError (a subclass of Exception) is raised for every document, password and I/O error.

Rust crate reference

The crates split docboss by concern. Most programs need docboss-core to open a document and one of the consumers after it.

Errors are thiserror enums per crate; docboss_core::Error wraps the readers' errors and adds Encrypted and Unsupported. No library function panics on input bytes: damaged input yields an error or a document with diagnostics.

use docboss_output::{to_html, HtmlOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = docboss_core::Options { password: Some("secret".into()) };
    let doc = docboss_core::open_with("locked.docx", &options)?;
    for diagnostic in &doc.diagnostics {
        eprintln!("{:?} {}: {}", diagnostic.severity, diagnostic.location, diagnostic.message);
    }
    let html = to_html(&doc, &HtmlOptions { standalone: true, ..HtmlOptions::default() });
    std::fs::write("locked.html", html)?;
    Ok(())
}

Limitations

The reader reports what it could not read: docboss diagnostics lists every approximated or dropped item. The conformance ledger has a row for every clause of the standards docboss reads, with a note on what is missing. The largest gaps:

Reading

• DOCX: w:altChunk content is skipped and reported. ActiveX controls and custom XML data binding are not read as content. Ruby text is ignored. Only the compatibilityMode compatibility setting is read.
• DOC: password-protected Word 6 and 95 files are refused. Word 6 and 95 files are read with their formatting, sections, headers, footers, tables, pictures and numbered paragraphs (ANLD), but their comments, endnotes and drawing objects, whose Word 6 records differ from Word 97's, and the equations of their Equation Editor objects are left out and reported; Word 2 files are read as text only. A Word 97 compound file whose directory is lost gives its text only (a Word 6 or 95 one is read in full). Freeforms and WordArt shapes are reported as dropped.
• DOCX and DOC: Equation Editor 3 objects keep their preview picture and give their equation as text and LaTeX; MathType's MTEF 4 and 5 are not read, and the object is reported.
• RTF is detected and refused. Flat OPC XML is not read: it is refused as an unknown format.

Layout and rendering

• Shaping covers Arabic, Hebrew and combining marks; Indic, Thai and other scripts that reorder or stack glyphs are not shaped, cursive attachment (GPOS type 3) is not applied, and Latin text gets no discretionary ligatures. Right-to-left sections (w:bidi in w:sectPr: column order, gutter side) and vertical sections (tbRl) lay out left to right.
• No column balancing. Text wraps around floating images, text frames and floating tables in the body. Text in a table cell or text frame does not wrap around a float anchored there (the row grows to hold the float, which is drawn over the text); floats in headers and footers do not push body text aside; a table beside a float is not narrowed; text wraps around a turned drawing as if it were not turned. docboss diagnostics --layout reports each of these.
• Shapes draw solid and gradient fills; picture and pattern fills and effects (shadows, glow, 3-D) are not drawn. SmartArt without its saved drawing shows an empty frame; 3-D, radar, stock, surface, bubble and bar-of-pie charts show an empty frame too. Office Math stretches delimiters by scaling the glyph rather than with the font's variants.
• Conditional formatting from table styles is not applied.
• CFF2 fonts are refused; TIFF pictures draw a placeholder. WMF and EMF pictures are played (EMF+ records are skipped in favour of the EMF ones); their text is not extracted.
• Tracked changes render as the final text, without revision marks.

Writing

• Embedded fonts are not written (the font table lists names only), and no theme part is written.
• Raw HTML in Markdown is dropped, except <br>.
• Encrypted output is not supported.

Conformance

docboss keeps a ledger of the specifications it implements in ledger/Ledger/Catalogue/, one row per clause with the status docboss claims: implemented, incomplete, not implemented or out of scope. The specifications are ECMA-376 Parts 1 to 3 (5th edition), [MS-DOC], [MS-CFB], [MS-OLEPS], [MS-OSHARED], [MS-ODRAW], [MS-WMF], [MS-EMF] and PKWARE's APPNOTE.TXT; ledger/Ledger/Scope.lean names the clauses of each that must have a row.

The ledger is checked by Lean 4 on every push (make ledger-gate). Six theorems in ledger/Ledger/Gate.lean establish that every row sits in its own specification's file and names one of its chapters, that rows are unique, that every required clause has a row speaking to it, that every implemented row is cited by both implementation code and a test in the source tree, that every incomplete row is cited by implementation code and explains what is missing, that every other row explains itself, and that no citation names a clause its specification does not have. They are decided by Lean's compiled evaluator (native_decide), so they trust the Lean compiler as well as its kernel; the theorems of the reference implementations in ledger/Ledger/Reference/, whose vectors the Rust tests replay, are checked by the kernel alone. Citation counts below are the number of source comments naming the clause or a sub-clause of it, in implementation code and in tests.

This page is generated by make ledger-report. Edit the ledger, not the page.

ECMA-376 Part 1: Fundamentals and Markup Language Reference (5th edition, 2016)

11 WordprocessingML

15 Shared

17 WordprocessingML Reference Material

20 DrawingML - Framework Reference Material

22 Shared MLs Reference Material

ECMA-376 Part 2: Open Packaging Conventions (5th edition, 2021)

6 Abstract package model

7 Physical package model

8 Core properties

10 Digital signatures

ECMA-376 Part 3: Markup Compatibility and Extensibility (5th edition, 2015)

7 MCE Elements and Attributes

9 Semantic Definitions and Reference Processing Model

[MS-DOC]: Word (.doc) Binary File Format

2 Structures