Conversion Options

convert.ConvertToPdfWithOptions takes a *convert.Options alongside the document. It is the same conversion ConvertToPdf performs, since that function just passes nil, with control over field processing, fonts, page and font size defaults, and image encoding.

Fields left at their zero value are skipped rather than applied, so an Options with one field set changes only that one thing. DefaultFontSize is only read when it is greater than zero, and DefaultPageSize is only read when it differs from A4.

Processing fields

doc, err := document.Open("merge_fields.docx")
if err != nil {
    log.Fatalf("error opening document: %s", err)
}
defer doc.Close()

co := &convert.Options{
    ProcessFields:        true,
    EnableFontSubsetting: true,
}

c := convert.ConvertToPdfWithOptions(doc, co)

if err := c.WriteToFile("output/merge_fields.pdf"); err != nil {
    log.Fatalf("error converting document: %s", err)
}

ProcessFields handles one specific pairing. Before layout begins, the converter walks the body, every table cell, and every header and footer looking for field codes of the form SET name "value". Those become a name-to-value map, and any REF name field later in the document renders as the matching value. With ProcessFields off, the map is empty and REF fields render as nothing at all.

That is the whole of it. TOC, DATE and the rest of the field codes are unaffected by this option; see Convert a document to PDF for what the converter does evaluate on its own.

The font subsetting default

The godoc on EnableFontSubsetting says the default is true, and in practice that holds only when you pass no options at all. The check the converter makes is that options are nil, or that the flag is set. A *convert.Options value with EnableFontSubsetting left at the Go zero value therefore turns subsetting off, and the PDF comes out larger than the same document converted with ConvertToPdf.

Set it explicitly to true in any Options you build. The example does not, which is why the snippet above adds it.

Limitations

DefaultPageSize is typed as convertutils.PageSize, and convertutils is an internal package. The named constants for A3, A5, Letter and Legal cannot be referenced from outside the library, so the field is not usable as intended from application code. A4 is the default and is what you get. This is reported as a library defect.

RtlFontFile supports one font per document. Mixed right-to-left content in more than one typeface is not addressable through it.

Fonts named in FontFiles and FontDirectory go through the same registration path as convert.RegisterFontsFromDirectory, which means TTF only and failures logged at debug level rather than returned. Registration failures here do not stop the conversion; the affected text falls back to Helvetica.

DefaultImageEncoder has less reach than it used to. Since UniPDF v5, images that arrive already JPEG-encoded are embedded verbatim, so setting DCTEncoder does not recompress them and its quality setting will not shrink the output.

Run the example

The example converts merge_fields.docx, a document built from SET and REF pairs, with ProcessFields turned on. Convert the same file through the plain conversion example and compare: the field positions come out blank there.

git clone https://github.com/unidoc/unioffice-examples.git
cd unioffice-examples/document/convert_to_pdf_options
go run main.go

If this is your first time using UniOffice, follow the getting started guide to create an API key and set up your development environment.