如何编写Pandoc Lua过滤器仅包裹AST顶级Para块为自定义样式Div

已实现的BlockQuote转换过滤器 #

用户已编写以下Lua过滤器，将Markdown的BlockQuote替换为带自定义Word样式的Div：

function BlockQuote(elem)
  return pandoc.Div (elem.content, {["custom-style"] = "Displayed quotation"})
end

核心需求与问题解答 #

1. 仅修改AST中的顶级Paragraph，避免嵌套元素内的Para #

要区分顶级和嵌套Para，最直接的方式是遍历AST时跟踪元素的上下文层级：

• Pandoc的Lua过滤器默认递归遍历AST，单个Para处理函数会匹配所有层级的Para。我们可以通过自定义遍历逻辑，在遍历过程中记录当前是否处于顶级（未被其他块元素包裹）。
• 实现思路：
  1. 定义全局变量is_top_level，初始设为true。
  2. 编写容器类块元素（如Div、BlockQuote、List等）的处理函数，进入这类元素时将is_top_level设为false，处理完成后恢复原值。
  3. 在Para处理函数中，仅当is_top_level为true时，才将Para包裹为目标Div。
• 示例代码片段：

local is_top_level = true

-- 处理容器元素，切换层级标记
local function handle_container(elem)
  local prev_state = is_top_level
  is_top_level = false
  local processed = elem:walk({})
  is_top_level = prev_state
  return processed
end

-- 对所有容器类块元素应用层级切换
function Div(elem) return handle_container(elem) end
function BlockQuote(elem) return handle_container(elem) end
function List(elem) return handle_container(elem) end
function Table(elem) return handle_container(elem) end

-- 仅处理顶级Para
function Para(elem)
  if is_top_level then
    return pandoc.Div(elem.content, {["custom-style"] = "Your Special Style"})
  end
  return elem -- 嵌套Para不修改
end

2. 检测段落的前序元素类型 #

要获取段落的前序元素，需要遍历整个文档的顶级块元素列表，单个Para处理函数无法直接获取上下文的前序元素：

• 实现思路：
  1. 编写Doc处理函数，直接操作文档的blocks列表（所有顶级块元素）。
  2. 遍历列表时记录前一个元素的类型，遇到Para时判断前序元素类型并决定是否包裹。
• 示例代码片段：

function Doc(doc)
  local processed_blocks = {}
  local prev_type = nil
  for _, block in ipairs(doc.blocks) do
    if block.t == 'Para' then
      -- 根据前序元素类型判断是否包裹Div
      local wrap = false
      -- 章节开头：前序是标题或文档第一个元素
      if prev_type == nil or prev_type == 'Header' then
        wrap = true
      -- 前序是块引用
      elseif prev_type == 'BlockQuote' then
        wrap = true
      end
      if wrap then
        table.insert(processed_blocks, pandoc.Div(block, {["custom-style"] = "Your Special Style"}))
      else
        table.insert(processed_blocks, block)
      end
    else
      table.insert(processed_blocks, block)
    end
    -- 更新前序元素类型
    prev_type = block.t
  end
  return pandoc.Doc(processed_blocks, doc.meta)
end

• 注：该方法仅针对顶级块元素的顺序，嵌套元素内的Para不会被处理，符合只修改顶级Para的需求。

3. Lua语法与Pandoc AST相关疑问 #

(1) elem是不是表？Lua中所有内容都是表吗？

• elem是Pandoc自定义的用户数据类型，但Lua中可像访问表字段一样操作它的属性。
• Lua中并非所有内容都是表：数字、字符串、布尔值、nil等基本类型，以及函数、用户数据、线程都是独立于表的类型，表只是复合类型的一种。

(2) variable_name.field_name（如elem.content）的含义？

• 这种语法用于访问对象的属性/字段，对于Pandoc AST元素：
  • BlockQuote、Div这类容器块元素的content字段，存储它们包含的子块元素列表；
  • Header元素的level字段，存储标题层级（1-6）；
  • 所有AST元素的t字段表示其类型（如Para、Header）。

(3) 如何查询AST元素的可用字段？

• 可查看Pandoc官方文档的AST元素参考，里面列出了所有块元素、行内元素的字段和类型；
• 也可在Lua过滤器中用print(require('inspect')(elem))（需提前安装inspect库）打印元素结构，直观查看字段信息。

(4) 适合初学者的Pandoc Lua教程

• Pandoc官方文档的Lua Filter章节是最权威的入门资料，涵盖基础概念到示例；
• 从官方提供的示例过滤器（如处理标题、列表的简单过滤器）入手，逐步理解遍历和修改AST的逻辑；
• 参考Pandoc社区整理的Lua过滤器合集，学习他人实现思路，结合自身需求调试修改。

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