fix(cli): write the --show-layout HTML export as UTF-8

[Anai-Guo]

The --show-layout arm of the split-page HTML export writes the serialized page through a bare open(fname, "w"):

https://github.com/docling-project/docling/blob/main/docling/cli/main.py#L541

Text-mode open() without encoding= encodes with locale.getpreferredencoding(False). On Windows that is a legacy code page — cp1252 / cp936 / cp932 depending on the system locale — so converting any document whose text is not representable in that code page aborts at the very last step, after all the parsing and layout work is already done:

UnicodeEncodeError: 'charmap' codec can't encode characters in position 4112-4115: character maps to <undefined>

Curly quotes, en/em dashes, bullets and accented Latin are enough to trigger it on cp1252; on cp936/cp932 anything outside the local script is.

Why this one line is the odd one out

Every other export path already writes UTF-8 explicitly:

• the else arm of this very if calls save_as_html();
• the neighbouring DocLang and Chunks exports in the same function use fname.open("w", encoding="utf-8");
• in docling-core, every save_as_* bottoms out in filename.write_text(..., encoding="utf-8") — including save_as_html and the DocTags writer, which persists serializer.serialize().text, the same expression this branch writes.

An AST sweep of the docling/ package finds no other text-mode open() without encoding=; the remaining bare open calls are all tarfile.open(..., "r:gz"). So this is the last site in the package that inherits the locale encoding, and it makes --show-layout the only HTML export that is not portable.

This is the same failure mode as the previously reported #221, #230, #578, #579 and #598 — all 'charmap' codec errors on Windows — surviving in a branch added later.

Reproduction

Exercising the exact expression from the CLI against the real serializer, on Windows with locale.getpreferredencoding(False) == 'cp1252', CPython 3.12.10, docling-core 2.89.0:

from docling_core.transforms.serializer.html import HTMLDocSerializer, HTMLParams
from docling_core.types.doc.document import DoclingDocument
from docling_core.types.doc.labels import DocItemLabel

doc = DoclingDocument(name="repro")
doc.add_text(label=DocItemLabel.TEXT, text="Le “Café” — résumé • 中文文档")
ser_res = HTMLDocSerializer(doc=doc, params=HTMLParams()).serialize()

with open("current.html", "w") as fw:          # current CLI code path
    fw.write(ser_res.text)
# UnicodeEncodeError: 'charmap' codec can't encode characters in position 4112-4115

with open("fixed.html", "w", encoding="utf-8") as fw:   # this PR
    fw.write(ser_res.text)
# writes fine, round-trips

The fix is to pass encoding="utf-8", matching the rest of the export code. Behaviour is unchanged on platforms whose preferred encoding is already UTF-8.

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

_{🤖 Generated with Claude Code}

[github-actions]

✅ DCO Check Passed

Thanks @Anai-Guo, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?: