How gomutex/godocx works
Purpose and public entry points
Godocx is a pure-Go library (Go 1.18+) for creating, modifying, reading, and writing DOCX/Office Open XML documents. Consumers primarily use the root package’s document lifecycle APIs, then fluent document-content APIs. Key entry points: document.go, docx/document.go, docx/writer.go.
Document lifecycle and façade
The root package exposes document construction/opening and delegates implementation to the docx package. The docx.Document model owns document state and operations such as adding content and saving. This is the main API boundary between application code and OOXML internals.
Paths: document.go, docx/document.go, docx/doc.go.
High-level Word document composition
docx provides authoring primitives for body content: paragraphs/runs, headings, tables, hyperlinks, pictures, numbering, styles, and document properties. These components mutate the in-memory document model rather than directly emitting files.
Paths: docx/paragraph.go, docx/run.go, docx/table.go.
OOXML WordprocessingML model
The wml layer represents the XML vocabulary behind Word documents. wml/ctypes contains composite XML structures for paragraphs, runs, tables, sections, headers/footers, and formatting; wml/stypes supplies XML simple/enumerated types. This layer is the schema-shaped boundary used by higher-level docx composition.
Paths: wml/ctypes/para.go, wml/ctypes/table.go, wml/stypes/doc.go.
DrawingML and embedded graphics
Drawing support is modeled separately through dml, including inline/anchored drawings, position/wrapping, graphic frames, and picture/blip structures. The document picture API connects user-level image insertion to these DrawingML representations and document relationships.
Paths: docx/pic.go, dml/drawing.go, dml/dmlpic/pic.go.
Package parts, relationships, and serialization
DOCX is handled as a ZIP-based Open Packaging Convention container. The packager layer manages ZIP creation/extraction, package URIs, and .rels relationship parts. docx defines package parts such as document XML, content types, styles, numbering, core properties, and relationships, then writes them into the archive.
Paths: packager/zip.go, packager/rels.go, docx/rels.go.
Primary flows and boundaries
For creation: caller → root/document façade → docx content APIs → WML/DML object graph → writer/package-part assembly → packager ZIP output (.docx). For reading: DOCX ZIP → package unpacking/relationship resolution → XML-backed docx model exposed to callers. The material external format is Microsoft DOCX/OOXML; there are no service, database, or web-runtime dependencies indicated. Default document scaffolding is sourced from templates/default.docx.
Paths: docx/writer.go, packager/unpack.go, templates/default.docx.
Main entry points: document.go Document model · writer.go Writer and parts · paragraph.go Content APIs · pic.go Picture API
Components 14
Public API
- Root document façade · Construction and open lifecycle entry points.
document.go
Document Authoring
- Document model · Owns document state and save operations.
docx/document.go - Content APIs · Paragraphs, runs, and tables mutate the document model.
docx/paragraph.go - Picture API · Connects image insertion to drawings and relationships.
docx/pic.go - Writer and parts · Assembles document XML and package parts.
docx/writer.go
OOXML Models
- WordprocessingML composites · Schema-shaped paragraphs, runs, tables, sections, and formatting.
wml/ctypes/para.go - WordprocessingML simple types
wml/stypes/doc.go - DrawingML graphics · Inline and anchored drawing structures.
dml/drawing.go
DOCX Packaging
- Relationships · Defines OOXML part relationships.
docx/rels.go - ZIP packager · Creates DOCX ZIP containers and relationship parts.
packager/zip.go - DOCX unpacker · Extracts packages for reading.
packager/unpack.go - Default scaffold
templates/default.docx
Other components
- Library consumer
- DOCX / OOXML file
Connections 17
- Library consumer → Root document façade: create or open
- Root document façade → Document model: delegates
- Document model → Content APIs: exposes
- Content APIs → WordprocessingML composites: builds
- WordprocessingML composites → WordprocessingML simple types: uses
- Content APIs → Picture API: inserts images through
- Picture API → DrawingML graphics: builds
- Picture API → Relationships: creates links
- Document model → Writer and parts: saves through
- Writer and parts → WordprocessingML composites: serializes
- Writer and parts → Relationships: writes
- Writer and parts → ZIP packager: packages parts
- Default scaffold → Document model: initial scaffolding
- ZIP packager → DOCX / OOXML file: writes
- DOCX / OOXML file → DOCX unpacker: reads
- DOCX unpacker → Document model: reconstructs model
- DOCX unpacker → Relationships: resolves