如何在Hakyll中集成pandoc-crossref实现公式交叉引用

问题描述 #

我正在用Hakyll搭建一个侧重学术与数学内容的静态网站，已成功集成参考文献功能（代码如下），现在想借助pandoc-crossref实现公式交叉引用，但不清楚如何将其纳入编译链，猜测可以用pandocCompileWithTransformM但不知道怎么和现有参考文献功能结合。

现有编译链代码：

pandocComplilerWithBibAndOptions :: Compiler (Item String)
pandocComplilerWithBibAndOptions = do
    csl <- load $ fromFilePath "apa.csl"
    bib <- load $ fromFilePath "bibliography.bib"
    fmap write (getResourceString >>= read csl bib)
    where
        read = readPandocBiblio readerOptions
        write = writePandocWith writerOptions
        readerOptions = defaultHakyllReaderOptions {
            readerExtensions = newExtentions <> pandocExtensions
        }
        writerOptions = defaultHakyllWriterOptions {
            writerExtensions = newExtentions <> pandocExtensions,
            writerHTMLMathMethod = MathJax ""
        }
        newExtentions = extensionsFromList  [Ext_tex_math_double_backslash,
                                             Ext_citations,
                                             Ext_latex_macros]

main :: IO ()
main = hakyll $ do
    -- 其他配置...

    match "posts/*" $ do
        route $ setExtension "html"
        compile $ pandocComplilerWithBibAndOptions
            >>= loadAndApplyTemplate "templates/post.html"    postCtx
            >>= loadAndApplyTemplate "templates/default.html" postCtx
            >>= relativizeUrls

    match "*.bib" $ compile biblioCompiler
    match "*.csl" $ compile cslCompiler

    -- 其他配置...

解决方案 #

1. 添加依赖 #

在项目构建配置文件（如cabal.yaml或.cabal）中添加pandoc-crossref依赖，确保版本与你使用的pandoc版本兼容：

# 示例cabal.yaml片段
build-depends:
  base >= 4.14 && < 5,
  hakyll >= 4.16,
  pandoc >= 2.19,
  pandoc-crossref >= 0.3.15.0

2. 导入必要模块 #

在站点代码文件顶部添加以下导入：

import Text.Pandoc.CrossRef (crossrefWith)
import Text.Pandoc.CrossRef.Options (defaultCrossRefOptions)

3. 修改编译函数，集成crossref #

调整原编译函数，在处理完参考文献后对Pandoc AST应用crossref转换：

pandocComplilerWithBibAndOptions :: Compiler (Item String)
pandocComplilerWithBibAndOptions = do
    csl <- load $ fromFilePath "apa.csl"
    bib <- load $ fromFilePath "bibliography.bib"
    -- 读取资源 → 处理参考文献 → 应用crossref转换 → 生成HTML
    doc <- getResourceString >>= readPandocBiblio readerOptions csl bib
    crossrefDoc <- traverse (crossrefWith defaultCrossRefOptions) doc
    return $ writePandocWith writerOptions crossrefDoc
    where
        readerOptions = defaultHakyllReaderOptions {
            readerExtensions = newExtensions <> pandocExtensions
        }
        writerOptions = defaultHakyllWriterOptions {
            writerExtensions = newExtensions <> pandocExtensions,
            writerHTMLMathMethod = MathJax ""
        }
        -- 添加crossref所需的扩展
        newExtensions = extensionsFromList  [Ext_tex_math_double_backslash,
                                             Ext_citations,
                                             Ext_latex_macros,
                                             Ext_raw_attribute]

4. 验证使用方式 #

在Markdown文档中使用pandoc-crossref语法添加公式引用：

$$
E = mc^2
$$ {#eq:emc2}

根据公式\ref{eq:emc2}，我们可以推导质能转换的核心逻辑...

关键说明 #

• crossrefWith defaultCrossRefOptions使用默认配置处理引用，可自定义CrossRefOptions调整编号规则、引用格式等。
• 必须先处理参考文献再应用crossref，确保crossref能基于完整的文档AST生成正确编号。
• 添加Ext_raw_attribute扩展是为了支持pandoc-crossref识别LaTeX环境标记，保证引用逻辑正常工作。

内容的提问来源于stack exchange，提问作者fhchl