docx

Documentation

Overview

Package docx renders markdown to a Word document (.docx). Importing it (for side effects) registers the "docx" format.

A .docx is an Office Open XML package: a zip of XML parts. This converter hand-builds them with the standard library (archive/zip) — no dependency — keeping md2's "pure Go by default" philosophy. The parts are:

• [Content_Types].xml declares the content type of each part
• _rels/.rels package root relationships (→ document, core props)
• word/document.xml the document body (built from the markdown AST)
• word/_rels/document.xml.rels document relationships (styles, numbering, external hyperlinks, embedded images)
• word/styles.xml Normal/Title/Heading1..6 paragraph styles. Headings carry w:outlineLvl so Word's Navigation pane and auto-TOC work.
• word/numbering.xml bullet + ordered list numbering definitions
• docProps/core.xml dc:title / dc:creator (the shared -title/-author)
• word/media/img{N}.{ext} embedded local images

Unlike the epub converter (which reuses the html pipeline), docx maps the goldmark AST directly to WordprocessingML — the text converter's block/inline switch is the structural template. Headings, paragraphs, lists (native Word numbering, nested), code blocks (syntax-highlighted, boxed), blockquotes, thematic breaks, GFM tables, bold/italic, inline code, links and local images are supported; enabled diagrams (-render) are rasterized to embedded PNGs.

The implementation is split across files within this package:

• docx.go the Converter, Render (zip assembly) and the builder type
• blocks.go block-level rendering (headings, lists, code, tables, ...)
• inline.go inline rendering (runs, formatting, links, images, drawings)
• parts.go the static XML part templates and the dynamic part builders

Local images referenced by relative paths are embedded as media parts, resolved against the input file's directory (via the optional PathConverter). Remote (http(s)://) and data: image references fall back to their alt text.

Index

• Variables
• func Render(src []byte, baseDir string) ([]byte, error)
• type Converter
  • func (Converter) Convert(src []byte, w io.Writer) error
  • func (Converter) ConvertFrom(src []byte, srcPath string, w io.Writer) error

Variables

var DiagramRasterizer func(source []byte, kind string) ([]byte, error)

DiagramRasterizer renders a diagram's fenced source to a PNG in the given diagram language ("mermaid"/"d2"/"plantuml"), for embedding in the document. Wired by the chrome package (which owns the headless browser); nil when no browser backend is linked, in which case enabled diagrams stay code blocks. Mirrors html.Rasterizer's inversion so docx does not import chrome.

Functions

func Render

func Render(src []byte, baseDir string) ([]byte, error)

Render converts markdown into the bytes of a complete .docx file. Relative image references are resolved against baseDir and embedded.

Types

type Converter

type Converter struct{}

Converter renders markdown source to a Word (.docx) document.

func (Converter) Convert

func (Converter) Convert(src []byte, w io.Writer) error

func (Converter) ConvertFrom

func (Converter) ConvertFrom(src []byte, srcPath string, w io.Writer) error

ConvertFrom is Convert with the input file path provided, so relative image references can be resolved against its directory and embedded.