microsoft / microsoft/markitdown
DOCX: Heading 7-9 styles lose heading structure entirely (render as plain paragraphs)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 186k
- Forks
- 13.7k
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 49
Description
Description
Word defines Heading styles 1 through 9, but the DOCX converter (via mammoth's default style map) only maps Heading 1-6. Paragraphs styled Heading 7, 8, or 9 come through as plain <p> text, so their heading structure is silently dropped from the markdown.
Reproduction
import io
from docx import Document
from markitdown import MarkItDown, StreamInfo
doc = Document()
for level in range(1, 10):
doc.add_heading(f"H{level}", level=level)
buf = io.BytesIO(); doc.save(buf); buf.seek(0)
print(MarkItDown().convert_stream(buf, stream_info=StreamInfo(extension=".docx")).markdown)
# H1..H6 render as #..###### but H7, H8, H9 render as plain paragraphs
Deep heading levels are common in legal and technical-spec documents.
Expected behavior
Markdown has no level past 6, so 7-9 clamp to ###### rather than losing the heading entirely.
Environment
markitdown main (945314a), python-docx + mammoth current
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the DOCX converter's Mammoth style-map handling, then run the provided python-docx reproduction against the current implementation. The fix is done when Heading 7, 8, and 9 produce level-6 Markdown headings instead of plain paragraphs, while Heading 1-6 behavior remains unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- content
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 75/100