Backend

Word documents

internal/docx writes .docx files: a page size, a named font at a given size, justified text, a line spacing, and a page break before each chapter. It is in every project, and it travels on grit upgrade.

This is not the list export. A resource already exports its filtered list as CSV, XLSX and JSON, and a Word table of rows is that again in a format that holds it worse. What a list export cannot produce is a document, and the formatting is usually not a preference: a university department or a government office specifies Times New Roman 12pt, justified, 1.5 spacing and a page break per chapter, and marks against it. Getting those wrong costs the person submitting it.

The document a scheme asks for

Submission() returns that combination, because it is specified often enough that every project otherwise writes it out again:

internal/handlers/proposal_handler.go
import "myapp/internal/docx"
func (h *ProposalHandler) Download(c *gin.Context) {
proposal, err := h.service().One(h.ctx(c), c.Param("id"))
if err != nil {
respond.NotFound(c, "Proposal not found")
return
}
doc := docx.New(docx.Submission()) // Times New Roman 12pt, justified, 1.5, 1in
doc.Heading(1, proposal.Title)
doc.Centered(proposal.Author)
for _, chapter := range proposal.Chapters {
doc.Chapter(chapter.Title) // starts a new page
doc.Para(chapter.Body)
}
b, err := doc.Bytes()
if err != nil {
respond.Internal(c, err)
return
}
c.Header("Content-Disposition", docx.Attachment(proposal.Title+".docx"))
c.Data(http.StatusOK, docx.ContentType, b)
}

Attachment is not decoration. A filename holding a quote or a newline either truncates the header or injects another one, and a filename is the first thing in a response to come from user input. It strips what is unsafe and also sends the RFC 5987 form, so an accented or non-Latin title survives.

Style

FieldTypeWhat it does
FontstringA font name, "Times New Roman". Empty means Calibri.
Sizefloat64Points. Zero means 11.
LineSpacingfloat641, 1.5, 2. Zero means single.
JustifyboolJustify body text. Headings, titles and table cells are never justified.
MarginMarginInches on each side. Zero means one inch all round. Inches because every house style is written in inches or centimetres and nobody has been asked for a 1440 twip margin.
LandscapeboolRotate the page.

Primitives

CallWhat it does
New(style)A new document with style as its default: font, size, line spacing, justification, margins, portrait or landscape.
Heading(level, text)A heading at level 1 to 3, as a named Word style rather than bold text. This is what fills the navigation pane and an automatic table of contents.
Chapter(title)A level 1 heading that starts a new page, using pageBreakBefore so the break moves with the heading when the text above it grows.
Para(text)A paragraph in the document default.
Centered(text)A centred paragraph, whatever the default alignment is. A title justified across the page is stretched into something nobody asked for.
Rich(runs...)A paragraph whose emphasis changes mid-sentence. Each Run carries Bold, Italic and Underline.
Bullet(text, level)A bulleted list item, nine levels.
Numbered(text, level)A numbered list item, nine levels.
Table(headers, rows)A bordered table. Pass no headers for a table with no header row.
PageBreak()An explicit page break. Prefer Chapter when the next thing is a heading.
Bytes() / WriteTo(w)Render. Nothing is written until one of these is called.

A whole report in one call

RenderReport is the pre-built template, the same arrangement internal/pdf has with RenderInvoice. Copy report.go as a starting point for a proposal, a dissertation, a tender response or a board paper:

b, err := docx.RenderReport(docx.Report{
Title: "An Assessment of Water Access in Mukono District",
Author: "A Student",
Date: time.Now(),
Chapters: []docx.ReportChapter{
{Title: "Introduction", Paragraphs: []string{intro}},
{Title: "Methodology", Sections: []docx.ReportSection{{
Heading: "Sampling",
Bullets: []string{"Forty households", "Two sub-counties"},
Table: &docx.ReportTable{Headers: []string{"Sub-county", "N"}, Rows: rows},
}}},
},
}, docx.Submission())

Why there is no dependency

A .docx is a zip of XML parts, and this writes them with archive/zip and encoding/xml from the standard library. The Go libraries for this are either thinly maintained or AGPL, and an AGPL dependency inside a framework other people build commercial products on is a licence decision nobody would choose deliberately. The subset a report needs is small enough that owning it costs less than depending on one.

The package ships its own tests, which a project can run. They were written against an independent OOXML reader rather than against the writer's own output, and that caught two faults before any of this shipped: a missing <w:tblGrid>, which the schema requires and Word silently tolerates, and the font living only in docDefaults, so a reader asking the Normal style what font it was got nothing. The second is exactly the claim a marking scheme is checked against.

Citations

A document with a bibliography needs a CSL processor, and that belongs on the client today. See citations for why, and for the one rule that matters: render once, persist the result, and have the server read it rather than derive it a second time.