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.
The document a scheme asks for
Submission() returns that combination, because it is specified often enough that every project otherwise writes it out again:
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, 1indoc.Heading(1, proposal.Title)doc.Centered(proposal.Author)for _, chapter := range proposal.Chapters {doc.Chapter(chapter.Title) // starts a new pagedoc.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
| Field | Type | What it does |
|---|---|---|
| Font | string | A font name, "Times New Roman". Empty means Calibri. |
| Size | float64 | Points. Zero means 11. |
| LineSpacing | float64 | 1, 1.5, 2. Zero means single. |
| Justify | bool | Justify body text. Headings, titles and table cells are never justified. |
| Margin | Margin | Inches 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. |
| Landscape | bool | Rotate the page. |
Primitives
| Call | What 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.
