epub to docx: footnotes formatting lost

[EngferLaygue]

I'm converting a epub file to docx. The epub contains hundreds of footnotes, defined using
<aside epub:type="footnote"> elements across multiple .xhtml files. These notes are referenced via <a href="#note-id"> links, and the epubvalidates correctly and displays as expected in Calibre and other readers.

When converting the epub to docx using:

pandoc input.epub -o output.docx

Pandoc consistently omits a large number of footnotes. The resulting .docx includes only a subset of the expected notes, and the following warnings are issued:

[WARNING] Note with key 'N002109' defined at line XXXX but not used.
[WARNING] Note with key 'N002127' defined at line XXXX but not used.
...

Also after converting, the original footnote links remain present as hyperlinks in the body text, even when the corresponding footnotes are missing from the output.

These notes are correctly defined and referenced in the epub, yet Pandoc fails to include them in the docx output.

My epub uses three distinct footnote styles, which I need to preserve in the docx output:

• Asterisks (*, **, ***)
• Alphabetical markers (a, b, c, ...)
• Numeric markers (for footnotes and for endnotes)

These distinctions must be retained in the final docx. Pandoc currently flattens or omits this structure entirely, and in some cases fails to include the notes at all.

I've confirmed that:

• The epub structure is valid and readable
• The <aside> elements are properly formed and contain note content
• The <a href="#note-id"> links are present in the body text
• The issue is not global: some notes (from the numerical footnotes markers) are correctly included

Is there a known limitation in Pandoc’s epub → docx conversion regarding footnote recognition and is there a way to preserve custom footnote marker styles (asterisks, alphabet, numbers) in the docx output?

thanks!

using:
pandoc 3.8
Features: +server +lua
Scripting engine: Lua 5.4

[jgm]

Preserving markers is out of scope. There is no way pandoc can do that with its current document model.

However, we could take a look at why some footnotes are being omitted. We'd need to see the epub, or a shorter version that suffices to reproduce the issue.