microsoft / microsoft/markitdown

DOCX: internal TOC / cross-reference hyperlinks emit dead [text](#_Toc…) anchors

Open Beginner friendly
#2,125 2 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

What happens

DOCX internal hyperlinks — Table-of-Contents entries and cross-references — are converted to Markdown links that point at the Word bookmark anchor, e.g. [Executive Summary](#_Toc12345). These #_Toc… / #_… anchors don't resolve in the standalone Markdown, so a real document's TOC becomes a block of dead links — noise for text/LLM consumption.

Minimal repro

markitdown[docx] 0.1.6, Python 3.12:

import tempfile, os
from docx import Document
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

doc = Document()
p = doc.add_paragraph()
hl = OxmlElement('w:hyperlink'); hl.set(qn('w:anchor'), '_Toc12345')   # internal anchor (a TOC entry)
r = OxmlElement('w:r'); t = OxmlElement('w:t'); t.text = "Executive Summary"
r.append(t); hl.append(r); p._p.append(hl)
path = os.path.join(tempfile.gettempdir(), "repro.docx"); doc.save(path)

from markitdown import MarkItDown
print(MarkItDown().convert(path).text_content)
Actual output
[Executive Summary](#_Toc12345)
Expected / suggestion

For internal-only anchors (a w:anchor with no external target), render the link text as plain text (or drop the dead #_anchor), so a TOC / cross-reference becomes readable text rather than dead links.

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 running the minimal DOCX reproduction with markitdown[docx] and inspect the DOCX hyperlink conversion path. Verify that internal-only w:anchor links such as _Toc12345 are rendered as readable plain text, while the output no longer contains dead #_Toc… anchors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.