使用pandoc API（writeEPUB3）生成EPUB时，注释会重复，且缺少索引编号

后端开发 2026-07-09

我需要用pandoc的 API来生成一个EPUB3，并用Haskell代码来编写，但用API的结果与pandoc CLI产生的结果不同（那样也可以）。

一个最小示例（已包含）会生成带有注释的文本（这是预期中的），并在一个水平分隔线之后附加注释，但没有索引号（要链接注释，至少需要一个索引号，否则无法将节点列表与文本连接）！

我觉得我还缺少某些样式，但对 'style.css'、'epub.css'、'style.html' 等的尝试并没有给出解决方案；我也很难看清写作者会去哪里查找这些文件。

要只显示弹出注释，我需要哪些样式？如果我想要弹出注释和带索引的注释列表呢？可以把水平线替换成一个标题吗？

这个最小示例——在执行 'pandoc -o note.epub c6note.md' 时生成的仅包含弹出注释的EPUB：

---
title: a single note 
---

a single note [^3] here 

[^3]: the note!

以及用于测试的Haskell代码

import Text.Pandoc  
import Data.ByteString.Lazy (toStrict)
import qualified Data.Text as T
import System.IO (writeFile)
import qualified Data.ByteString.Lazy as BL
import qualified Text.Pandoc.Class as PC

main :: IO ()
main = do
    mdfile   <- readFile "c6note.md"  
    let readerOpts = def { readerExtensions = enableExtension Ext_footnotes (readerExtensions def) }    
    res <- runIO  $ do 
        pan1 <-  readMarkdown readerOpts (T.pack mdfile)   
        ep3p  <- writeEPUB3 def pan1
        return ep3p
    case res of 
        Left err -> putStrLn . show $ err 
        Right ep -> 
                BL.writeFile "c6note.epub" ep

解决方案

问题是由于 writeEPUB3 函数的代码更新引起的，以及CLI Pandoc（我在Debian上使用的版本是3.1.11.1）与Pandoc API（我使用的版本是3.9.0.1）之间的版本差异。旧代码能够被我的EPUB阅读器（calibre 8.5和 foliate 3.3）正确解读，而新代码则无法输出正确结果。

似乎有几种可能的解决方案；例如把Pandoc的 API版本固定在3.8.7（EPUB代码更新前的最后一个版本），升级calibre并希望新代码在那里工作，或者使用 writeEPUB2，它为弹出注释生成带索引号的编号（普通、蓝色且不是上标），并在带有索引号的水平线之后显示注释文本。

最好能够选择只显示弹出注释，还是弹出注释以及一个带索引号的注释列表，并放在一个可选标题下。

API