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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#2,743 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@sun04222 ya está trabajando en esto.

Desde el 23/10/2026.

  • #2746 de @sun04222 — abierto

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
76/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
markdown, python
Área
documentation

Línea de trabajo

Lee packages/markitdown/src/markitdown/converters/_docx_converter.py y _markdownify.py, especialmente _CustomMarkdownify.convert_a, y luego reproduce el problema con los comandos proporcionados footnote.py y markitdown footnote.docx. Rastrea cómo se gestionan la referencia a la nota al pie de página y los identificadores de los elementos de lista de mammoth durante la conversión de HTML a Markdown. El trabajo estará terminado cuando la salida no contenga enlaces a anclas inexistentes e, idealmente, conserve la referencia y la nota como sintaxis de nota al pie enlazada.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
194k
Forks
14.5k
Merge medio
24 min
PR fusionados (30 d)
7

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de microsoft/markitdown

Todos los issues de microsoft/markitdown

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.