github.com/mmonterroca/docxgo
Advanced tools
Production-grade Microsoft Word .docx (OOXML) file manipulation in Go.
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.
interface{}, explicit error handling throughoutCurrent Version: v2.0.0-beta (95% complete)
Stability: Beta - Production Ready
Target Stable Release: Q1 2026
Test Coverage: 50.7% (improvement plan ready → 95%)
Completed Phases: 1-9, 11 (10 phases complete, 2 remaining)
Note: This library underwent a complete architectural rewrite in 2024-2025, implementing clean architecture principles, comprehensive testing, and modern Go practices. Phase 11 (Code Quality & Optimization) completed October 2025.
go get github.com/mmonterroca/docxgo
package main
import (
"log"
docx "github.com/mmonterroca/docxgo"
)
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)
}
}
package main
import (
"log"
docx "github.com/mmonterroca/docxgo"
"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)
}
}
package main
import (
"log"
docx "github.com/mmonterroca/docxgo"
)
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)
}
}
See the examples/ directory for comprehensive examples (11 working examples):
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
interface{}Core Document Structure
Text Formatting
Advanced Table Features (Phase 9 - Complete)
Images & Media (Phase 8 - Complete)
Fields & Dynamic Content (Phase 6 - Complete)
Headers & Footers (Phase 6 - Complete)
Styles System (Phase 6 - Complete)
Builder Pattern (Phase 6.5 - Complete)
Quality & Reliability (Phase 11 - Complete)
Phase 10: Document Reading (60% Complete - Core Features Working ✅)
Phase 12: Beta Testing & Release (In Progress)
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:
See docs/ERROR_HANDLING.md for comprehensive review.
# 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.
For Users:
For Developers:
Quick Links:
Optimized for real-world usage:
Benchmarks (coming in Phase 11.5):
Status: 100% Complete (October 2025)
Phase 11 delivered production-ready code quality:
Achievements:
Quality Metrics:
See docs/V2_DESIGN.md#phase-11 for complete statistics.
We welcome contributions! Please see CONTRIBUTING.md for:
git checkout -b feature/amazing-feature)go test ./...)MIT License
This means:
See LICENSE for full text.
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.
This project evolved through multiple stages:
Current Maintainer: Misael Monterroca (misael@monterroca.com)
GitHub: @mmonterroca
V2 Rewrite:
For complete project genealogy, see CREDITS.md.
Progress: ~95% complete (10 phases done, 2 remaining)
Phase 10: Document Reading (Not Started - ~15-20 hours)
Phase 12: Beta Testing & Release (In Progress)
v2.0.0-beta (Q4 2025 - Current)
v2.0.0-rc (Q1 2026)
v2.0.0 stable (Q1 2026 - Target: March 2026)
See docs/V2_DESIGN.md for detailed phase breakdown.
Please include:
go version)Comparison:
Made with ❤️ by Misael Monterroca
Star ⭐ this repo if you find it useful!
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Socket was named to the Rising in Cyber 2026 list, recognizing 30 private cybersecurity startups selected by CISOs and security executives.
Research
Socket detected 84 compromised TanStack npm package artifacts modified with suspected CI credential-stealing malware.
Security News
A dispute over fsnotify maintainer access set off supply chain alarms around one of Go’s most widely used filesystem libraries.