Question about DOCX style mapping (from HTML to DOCX)
There are no forum posts on this topic! Why don't you write one?
Hello!
I’m using the HTML → DOCX REST API and I’m trying to understand if/how styles are generated in the resulting Word document—specifically for lists.
In my source HTML, I’m using standard nested lists:
<ul>
<li>List item 1</li>
<li>
List item 2
<ul>
<li>Nested list item 1</li>
</ul>
</li>
</ul>
In the generated DOCX, the bullets render visually as a list (Word shows w:numPr, w:ilvl, w:numId in document.xml), but in Word’s Styles pane the list items show as “Normal + 12 pt, Black” rather than a list style like “List Bullet” / “List Bullet 2”, etc.
In the Styles Pane, when I select “In current document” I only see Normal + Heading styles, while all other styles appear only under “All styles”.
Could you clarify what’s supported here?
- Is it possible for the converter to apply built-in list paragraph styles (e.g., List Bullet, List Bullet 2, List Paragraph, List Number, etc.) to list items produced from <ul>/<ol>?
- If yes: how do we request/force that mapping? Is there a parameter, supported CSS attribute, or HTML pattern you recommend?
- Is it possible to include/apply custom paragraph styles (e.g., Bulletlevel1, Bulletlevel2, or any custom style name) in the generated DOCX and have list items use those styles? (I am assuming no)
If it helps, I can provide:
- the HTML snippet being converted
- the resulting document.xml, styles.xml, and numbering.xml (if present)
- screenshots of the Word Styles pane behavior
Let me know!
Edit: I have worked with `python-docx` library in the past and their documentation defines these kinds of styles in the Word document:
- built-in style: One of the set of 276 pre-set styles built into Word, such as “Heading 1”. A built-in style can be either defined or latent. A built-in style that is not yet defined is known as a latent style. Both defined and latent built-in styles may appear as options in Word’s style panel and style gallery.
- custom style: Also known as a user defined style, any style defined in a Word document that is not a built-in style. Note that a custom style cannot be a latent style.
In my question I am asking if it is possible to apply built-in styles to areas of text (for example, applying built-in list styles to lists), and _also_ if it would be possible to get custom styles in and then apply them to text.
Source: https://python-docx.readthedocs.io/en/latest/user/styles-understanding.html#glossary
Hello Paul!
Just an update on this: We have implemented support for built-in list style mapping.
The converter now explicitly applies the List Bullet style families (e.g., List Bullet, List Bullet 2, etc.) to list items produced from <ul> and <ol> tags. This ensures that:
- List items are semantically tagged with the correct Word styles rather than appearing as "Normal + overrides."
- These styles will now appear correctly in the Word Styles Pane under "In use."
- Users can globally modify the look of all lists by simply editing the built-in Word style.
You should see the changes, in the next few hours.
Regarding Custom Styles
We have decided not to support mapping to custom paragraph styles (e.g., Bulletlevel1). Doing so introduces significant complexity because it requires dynamic synchronization between the styles.xml and numbering.xml definitions. By sticking to the built-in Word list styles, we ensure the most robust and predictable behavior for the end user while maintaining full compatibility with Word's native list logic.
