如何在Pandoc及Hakyll项目中正确使用GitHub Alert功能？

问题描述 #

Pandoc的Ext_alerts扩展支持解析GitHub样式的alert，命令行测试可正常输出对应HTML：

echo "> [!WARNING]\n> 警告内容" | pandoc -t html -f gfm

但在Hakyll项目中手动配置该扩展后无效，直接用Pandoc代码测试也未得到预期结果：

λ> ropt = defaultHakyllReaderOptions { readerExtensions = getDefaultExtensions "gfm" }
λ> wopt = defaultHakyllWriterOptions { writerExtensions = getDefaultExtensions "gfm" }
λ> readerExtensions ropt
Extensions (fromList [Ext_alerts,Ext_auto_identifiers,Ext_autolink_bare_uris,Ext_emoji,Ext_footnotes,Ext_gfm_auto_identifiers,Ext_pipe_tables,Ext_raw_html,Ext_strikeout,Ext_task_lists,Ext_tex_math_dollars,Ext_tex_math_gfm,Ext_yaml_metadata_block])
λ> runPure $ writeHtml5String wopt =<< readMarkdown ropt  ("> [!WARNING]\n> 警告内容" :: Text)
Right "<blockquote>\n<p>[!WARNING]</p>\n<p>警告内容</p>\n</blockquote>"

错误原因 #

1. 阅读器类型不匹配：Ext_alerts是GFM（基于CommonMark）专属扩展，readMarkdown是传统Markdown阅读器，不支持该语法的解析逻辑，必须使用CommonMark/GFM阅读器。
2. Hakyll默认配置偏差：defaultHakyllReaderOptions默认使用Markdown格式阅读器，即使启用Ext_alerts，解析逻辑也无法适配GFM的alert规则。

解决方案 #

1. 直接用Pandoc代码实现Alert转换 #

改用readCommonMark（GFM基于CommonMark）或readFormat "gfm"加载正确的阅读器，同时确保扩展启用：

import Text.Pandoc
import Text.Pandoc.Extensions
import Control.Monad.IO.Class (liftIO)

main :: IO ()
main = do
  let -- 配置GFM阅读器选项，启用Ext_alerts
      ropt = defaultReaderOptions {
          readerExtensions = enableExtension Ext_alerts $ getDefaultExtensions "gfm"
      }
      -- 配置HTML写入选项，启用alert输出支持
      wopt = defaultWriterOptions {
          writerExtensions = enableExtension Ext_alerts $ getDefaultExtensions "gfm"
      }
      -- 完整的alert语法（必须包含内容行）
      input = "> [!WARNING]\n> 这是一条测试警告" :: Text
  -- 使用readCommonMark解析GFM内容
  result <- runIO $ writeHtml5String wopt =<< readCommonMark ropt input
  print result

也可用readFormat简化写法：

result <- runIO $ writeHtml5String wopt =<< readFormat "gfm" ropt input

执行后会输出正确的alert HTML结构：

<div class="warning">
<p>这是一条测试警告</p>
</div>

2. Hakyll项目中的正确配置 #

修改阅读器格式为gfm，并启用Ext_alerts扩展：

myPandocCompiler :: Compiler (Item String)
myPandocCompiler =
    pandocCompilerWithTransformM ropt wopt (pygmentsHighlight . shiftHeaders 1)
    where
        baseGFMExts = getDefaultExtensions "gfm"
        enabledExts = enableExtension Ext_alerts baseGFMExts
        ropt = defaultHakyllReaderOptions {
            -- 指定使用GFM格式阅读器
            readerFormat = Just "gfm",
            readerExtensions = enabledExts
        }
        wopt = defaultHakyllWriterOptions {
            writerExtensions = enabledExts
        }

注意事项 #

GitHub样式alert的语法必须完整：块引用的第一行是> [!TYPE]（TYPE可取值WARNING/INFO/NOTE等），后续必须跟至少一行内容（哪怕是空行），否则Pandoc会将其解析为普通块引用。

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