Convert docx to html

[darksoothingshadow]

Question

How do I convert a DOCX to HTML? How do I include a serializer?
…

[dosubot]

To convert a DOCX file to HTML with docling, use the DocumentConverter class to convert your file, then call export_to_html on the resulting document. This export step is the serializer—you can control what content gets included (like headers and footers) using the included_content_layers parameter. Here’s a minimal example:

from docling.document_converter import DocumentConverter, InputFormat
from docling_core.types.doc.document import ContentLayer

converter = DocumentConverter(allowed_formats=[InputFormat.DOCX])
result = converter.convert("your_file.docx")
html = result.document.export_to_html(
    included_content_layers={ContentLayer.BODY, ContentLayer.FURNITURE}  # BODY = main content, FURNITURE = headers/footers
)
with open("output.html", "w") as f:
    f.write(html)

This will include both the main body and any detected headers/footers in the HTML output. If you only want the main content, use {ContentLayer.BODY} instead. The export_to_html method is the built-in serializer for HTML output. For more advanced customization, you can iterate over document items and build your own serializer logic if needed [source].

Known limitations: complex or nested tables and some list formatting may not convert perfectly. Workarounds include preprocessing the DOCX, post-processing the HTML, or writing a custom serializer. For some documents, converting DOCX to PDF first and then running docling on the PDF can yield better results [source].

Recent updates have improved backend options and image handling, so make sure you’re using the latest version for best results [source].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[darksoothingshadow]

Can we apply certain settings to extend the nested-list support?

Expected behaviour:

• Entwurf Bürgerrechtsgesetz (BRG)
• Entwurf Gesetz über die politischen Rechte (GPR)
• Entwurf Gesetz über den Grossen Rat (GGR)
• Entwürfe für Revisionen folgender Erlasse:

// The following indented

• • Verordnung über Landrecht und das Gemeindebürgerrecht (VLG)

• Verordnung über die Urnenabstimmung (VUA)
• Verordnung über ausserordentliche Urnenabstimmung (VaU)
• Verordnung über die Landsgemeinde und die Gemeindeversammlungen (VLGV)
• Verordnung über das Initiativverfahren (VIV)
• Verordnung über das fakultative Finanzreferendum
• Personalverordnung (PeV)
• Geschäftsreglement des Grossen Rates (GrGR)
• Verordnung über die Finanzprüfung und die Geschäftsüberwachung (VFG)

• Bericht Folgegesetzgebung neue Verfassung, 2. Teil, Gesetzesebene (BRG, GPR, GGR)
• Bericht Folgegesetzgebung neue Verfassung, 2. Teil, Verordnungsebene

Result:

• Entwurf Bürgerrechtsgesetz (BRG)
• Entwurf Gesetz über die politischen Rechte (GPR)
• Entwurf Gesetz über den Grossen Rat (GGR)
• Entwürfe für Revisionen folgender Erlasse:
• Verordnung über die Urnenabstimmung (VUA)
• Verordnung über ausserordentliche Urnenabstimmung (VaU)
• Verordnung über die Landsgemeinde und die Gemeindeversammlungen (VLGV)
• Verordnung über das Initiativverfahren (VIV)
• Verordnung über das fakultative Finanzreferendum
• Personalverordnung (PeV)
• Geschäftsreglement des Grossen Rates (GrGR)
• Verordnung über die Finanzprüfung und die Geschäftsüberwachung (VFG)
• Bericht Folgegesetzgebung neue Verfassung, 2. Teil, Gesetzesebene (BRG, GPR, GGR)
• Bericht Folgegesetzgebung neue Verfassung, 2. Teil, Verordnungsebene

[dosubot]

There are currently no settings or configuration options in docling to extend or improve nested-list support for DOCX to HTML conversion. The backend and serializer logic already support nested lists if the document model contains them, but the key limitation is in how the DOCX is parsed: if the source DOCX uses true nested lists (not just visually indented bullets), docling should preserve the hierarchy in the HTML output. If your DOCX uses proper nested list styles, docling will output nested <ul>/<ol> structures; if not, the output will be flat, and there’s no runtime setting to change this behavior [source].

If you need to fix or extend nested-list support, you’ll need to either:

• Ensure your DOCX uses true nested lists (not just indentation or manual bullets).
• Post-process the HTML output to reconstruct the hierarchy.
• Programmatically adjust the DoclingDocument structure before export.

There’s ongoing discussion and work on improving nested-list detection and hierarchy recovery, but as of now, there’s no configuration or export option to enable this [source].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ceberam]

@darksoothingshadow thanks for your interest in Docling.
As @dosu mentioned, to convert a Docling docx document to HTML, you first parse it as DoclingDocument format and then you export it as HTML. In addition to the snippet above, you can also use the CLI in a single command:

docling --to html your_file.docx

To check if your case is a bug, could you please share or point to a docx file where you see a mismatch between the converted and the expected result?

[dosubot]

Docling's DOCX to HTML conversion—whether via CLI (docling --to html your_file.docx) or Python API—currently flattens nested lists in the output. This happens because the pipeline detects list items but doesn't reconstruct their hierarchy, even though the document model supports nested lists. There are no settings or configuration options to change this behavior right now; improving nested list support would require changes to the backend or custom post-processing of the HTML output [source].

If your DOCX uses true nested list styles and you still see a flat list in the HTML, that's a known limitation. If you have a sample DOCX that demonstrates a mismatch, sharing it will help the maintainers diagnose edge cases or bugs. For now, workarounds include manually post-processing the HTML to restore hierarchy or using a custom serializer. The team is actively working on better nested list detection and hierarchy recovery for future releases [source].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ceberam]

@darksoothingshadow I took your example above to create a docx document with a nested list (indented):

indented-list.docx

By converting it to markdown, you can see that docling identifies the nested list.

docling --to md indented-list.docx
cat indented-list.md
"""
- Verordnung über Landrecht und das Gemeindebürgerrecht (VLG)
- Verordnung über die Urnenabstimmung (VUA)
- Verordnung über ausserordentliche Urnenabstimmung (VaU)
- Verordnung über die Landsgemeinde und die Gemeindeversammlungen (VLGV)
- Verordnung über das Initiativverfahren (VIV)
- Verordnung über das fakultative Finanzreferendum
- Personalverordnung (PeV)
- Geschäftsreglement des Grossen Rates (GrGR)
- Verordnung über die Finanzprüfung und die Geschäftsüberwachung (VFG)
    - Bericht Folgegesetzgebung neue Verfassung, 2. Teil, Gesetzesebene (BRG, GPR, GGR)
    - Bericht Folgegesetzgebung neue Verfassung, 2. Teil, Verordnungsebene
"""

I will then close this issue. If this does not yet answer your question, please fee free to reopen it.