DOCX: footnote references and back-links point to anchors that don't exist in the Markdown

Aperta Adatta ai principianti
  • Qualcosa non va?
#2,743 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@sun04222 ci sta già lavorando.

Dal 23/10/2026.

  • #2746 di @sun04222 — aperta

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
76/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
markdown, python
Ambito
documentation

Direzione di ricerca

Leggi packages/markitdown/src/markitdown/converters/_docx_converter.py e _markdownify.py, in particolare _CustomMarkdownify.convert_a, quindi riproduci il problema con i comandi forniti footnote.py e markitdown footnote.docx. Traccia come mammoth gestisce il riferimento alla nota a piè di pagina e gli ID degli elementi dell’elenco durante la conversione da HTML a Markdown. Il lavoro è completato quando l’output non contiene link ad ancore mancanti e, idealmente, conserva il riferimento e la nota come sintassi di nota a piè di pagina collegata.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Converting a DOCX that has footnotes gives links such as [[1]](#footnote-1) and [↑](#footnote-ref-1), but no element in the Markdown has those ids, so every link is dead. mammoth's HTML has the ids (<a id="footnote-ref-1">, <li id="footnote-1">). They are lost in MarkItDown's HTML-to-Markdown step.

Reproduction

footnote.py writes a one-paragraph document with one footnote:

import zipfile

W = 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"'
REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
with zipfile.ZipFile("footnote.docx", "w") as z:
    z.writestr(
        "[Content_Types].xml",
        '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
        '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
        '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
        '<Override PartName="/word/footnotes.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml"/>'
        "</Types>",
    )
    z.writestr(
        "_rels/.rels",
        '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
        f'<Relationship Id="rId1" Type="{REL}/officeDocument" Target="word/document.xml"/>'
        "</Relationships>",
    )
    z.writestr(
        "word/_rels/document.xml.rels",
        '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
        f'<Relationship Id="rId1" Type="{REL}/footnotes" Target="footnotes.xml"/>'
        "</Relationships>",
    )
    z.writestr(
        "word/document.xml",
        f'<w:document {W}><w:body><w:p><w:r><w:t>Text</w:t></w:r>'
        '<w:r><w:footnoteReference w:id="1"/></w:r></w:p></w:body></w:document>',
    )
    z.writestr(
        "word/footnotes.xml",
        f'<w:footnotes {W}><w:footnote w:id="1"><w:p><w:r><w:t>A note.</w:t></w:r></w:p></w:footnote></w:footnotes>',
    )

python footnote.py
markitdown footnote.docx
Actual output
Text[[1]](#footnote-1)

1. A note. [↑](#footnote-ref-1)

mammoth's HTML for the same file (mammoth.convert_to_html) has both targets:

<p>Text<sup><a href="#footnote-1" id="footnote-ref-1">[1]</a></sup></p><ol><li id="footnote-1"><p>A note. <a href="#footnote-ref-1">↑</a></p></li></ol>
Expected output

No links to missing anchors. Ideally the footnote is kept as a footnote, for example in GFM footnote syntax:

Text[^1]

[^1]: A note.

Versions

markitdown 0.1.9 (markitdown[docx]), mammoth 1.13.0, markdownify 1.2.3, Python 3.14, Linux x86_64. main (7482c09) has no changes to the DOCX or HTML-to-Markdown code since 0.1.9.

Cause

DocxConverter passes mammoth's HTML to HtmlConverter. _CustomMarkdownify.convert_a writes [text](href) and drops the <a> element's id. markdownify's li conversion drops the <li> element's id. So the href="#footnote-…" links survive, but their targets don't.

Related

  • #2125 (open) and #314 (open): dead #_Toc… links from internal hyperlinks (TOC entries and cross-references, w:hyperlink w:anchor). Footnote references are a different construct, generated by mammoth.
  • PR #2131 (open, for #2125): unwraps w:hyperlink w:anchor in pre-processing. It would not change footnote links, which mammoth generates.
  • PR #2265 (open): renders every fragment-only link as plain text. That would remove these dead links too, but the reference and the note would no longer be connected.

Drafted with the help of an AI assistant; every reproduction was run and its output checked.

Lingua principale
Python
Stelle
194k
Fork
14.5k
Merge medio
22m
PR unite (30g)
5

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

  • Include un Dockerfile o un file Docker Compose
  • Nessun modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di microsoft/markitdown

Tutte le issue di microsoft/markitdown

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.