如何通过Lua过滤器在Pandoc中实现GLFM的Markdown文件引用？

核心问题分析 #

• 使用RawInline时，若指定的格式与最终输出格式不匹配（比如输出HTML但RawInline标记为markdown），Pandoc会直接忽略该节点，导致内容缺失。
• 直接返回字符串的话，Pandoc会将其视为普通文本，不会解析其中的Markdown语法。

正确实现方案 #

不要用RawInline或直接返回字符串，正确的做法是读取目标Markdown文件后，用pandoc.read将内容解析为Pandoc AST节点，再插入到原文档中。

修正后的Lua过滤器示例 #

function CodeBlock(block)
    -- 匹配GLFM的::include指令（假设指令格式为::include[目标文件路径]）
    local include_path = block.text:match('^::include%[(.*)%]$')
    if include_path then
        -- 读取目标文件内容
        local file = io.open(include_path, 'r')
        if not file then
            print("警告：无法打开文件 " .. include_path)
            return block -- 读取失败时保留原指令
        end
        local content = file:read('*a')
        file:close()
        
        -- 将读取到的Markdown内容解析为Pandoc AST
        local parsed_doc = pandoc.read(content, 'markdown')
        -- 返回解析后的内容块
        return parsed_doc.blocks
    end
    -- 非include指令则返回原代码块
    return block
end

关键细节说明 #

1. 指令匹配逻辑：上述示例假设::include是以代码块形式存在（GitLab GLFM中常见写法），如果你的指令是行内形式（比如::include[file.md]作为行内文本），需要修改为处理内联元素的函数：

function Inline(inline)
    if inline.t == 'Str' and inline.text:match('^::include%[.*%]$') then
        local include_path = inline.text:match('^::include%[(.*)%]$')
        local file = io.open(include_path, 'r')
        if not file then
            print("警告：无法打开文件 " .. include_path)
            return inline
        end
        local content = file:read('*a')
        file:close()
        -- 解析行内Markdown内容，提取内联元素
        local parsed_doc = pandoc.read(content, 'markdown')
        return parsed_doc.blocks[1].content
    end
    return inline
end

2. AST解析：pandoc.read会将Markdown文本转换为Pandoc内部的抽象语法树，这样无论最终输出格式是HTML还是其他，Pandoc都能正确渲染插入的内容。
3. 错误处理：添加文件读取失败的提示，避免出现静默丢失内容的情况。

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