microsoft / microsoft/markitdown

DOCX: Heading 7-9 styles lose heading structure entirely (render as plain paragraphs)

Open Beginner friendly
#2,530 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.