Plugins and Pandoc

Plugins and Pandoc

Leafmark extensions are Pandoc Lua filters plus optional Pandoc arguments. They can be project-owned (plugins) or theme-owned (themePlugins).

Simple filter

{
  "plugins": ["plugins/cleanup.lua"]
}

The string is resolved from the active project and passed as --lua-filter=<path>.

Structured plugin

{
  "plugins": [
    {
      "luaFilter": "plugins/layout.lua",
      "args": ["--wrap=none"],
      "pdfArgs": ["-V", "colorlinks=true"],
      "htmlArgs": ["--section-divs"],
      "docxArgs": []
    }
  ]
}

path is accepted as an alias for luaFilter. args applies to every format; the matching format array is appended for PDF, HTML, or DOCX.

Minimal Lua filter

function Header(header)
  if header.level == 1 then
    header.classes:insert("chapter-title")
  end
  return header
end

Refer to the Pandoc Lua filters manual for the complete AST API.

Execution order

For each output, Leafmark adds:

1. theme plugins;
2. project plugins;
3. pandoc.args;
4. the matching pandoc.pdfArgs, pandoc.htmlArgs, or pandoc.docxArgs.

Leafmark may also add bundled filters for author entries and bibliography page breaks. Pandoc processes filter arguments in command-line order.

Raw Pandoc arguments

Use the pandoc object when no custom filter is needed:

{
  "pandoc": {
    "args": ["--wrap=none"],
    "pdfArgs": ["-V", "papersize=letter"],
    "htmlArgs": ["--section-divs"],
    "docxArgs": ["--reference-doc=reference.docx"]
  }
}

Arguments are not validated by Leafmark. Check the installed Pandoc version because option availability can differ.

Resource paths

Pandoc searches the active project, parent project, input root, and Leafmark package resources. Plugin and config paths themselves resolve from the active project unless absolute.

Debugging filters

1. Run with --keep-build-files.
2. Inspect _merged.md in the output directory.
3. Temporarily remove other filters to isolate ordering problems.
4. Run the equivalent Pandoc command or a minimal Pandoc fixture directly.
5. Remember that PDF, HTML, and DOCX AST handling may differ.

Caution

Plugin arguments can override Leafmark defaults or make an invalid Pandoc command. Keep format-specific settings in the matching array and document any required external tools.