Extending existing writers in Lua API

[georgiy-belyanin]

Hello. Currently, I am working on a project involving Markdown with custom extensions including various custom-defined tags. Pandoc really helps to convert documents using other formats to this custom Markdown but these custom extensions require custom writers.

AFAIS, there is only one way to define extensible custom writers --- via Lua. Though it seems that the pandoc.scaffolding.Writer interface requires a user to define every method to write the document which is kind of boilerplate: the desired format is mostly markdown but with a few extensions.

Is it somehow possible to write an extension of the existing writer overriding only a few methods? It seems to me neither builtin library nor metatable magic helps with it.

I imagine the following syntax to implement this.

Writer = pandoc.writers.markdown

Writer.Block.Div = function(header)
    -- Custom div logic goes here...
end

[helpatbbf]

There's an experimental html writer and derived writer at https://github.com/BroadbandForum/pandoc-html-writer. I haven't touched this for a while and am not currently using it, but it might be of interest?

[wlupton]

Sorry, I posted as the wrong user. Should have been @wlupton.

[georgiy-belyanin]

Thank you! Unfortunately, it behaves as an extension for another custom-defined writer meanwhile we would like to extend the builtin one. Though the implementation might also be handy to create extensible custom writers. And examples on the relatively new writer API are helpful :).

[wlupton]

Yes. Looks like you should listen to @tarleb here!

[tarleb]

Currently, the best way to do this is to use a filter. I.e., writer a filter that handles the custom things and creates raw Markdown nodes.

For example:

Div = function (div)
  local result = div.content
  if div.classes:includes 'header' then
    div.content:insert(1, pandoc.RawBlock('markdown', 'This is a header div'))
  end
  return result
end

Use the Markdown flavor of your choice and replace only those elements, that need special handling.

[georgiy-belyanin]

Thank you! A few experiments with metatables showed that the following might be possible if there would be a way to render separate blocks/inlines in the provided format.

Writer.Blocks = {}
setmetatable(Writer.Blocks, {
  __call = function(a, b)
    -- It seems `b` would contain blocks. We might try to work with them...
    -- pandoc.write_blocks(b, 'markdown')
  end
  __index = function(a, b)
    -- It seems `b` would contain a block. We might try to work with it...
    -- pandoc.write_block(b, 'markdown')
  end
})

Such approach might allow to override specific kinds of block or handle something by the builtin writers. But these tricks require pandoc.write_blocks(blocks[, format, opts]), pandoc.write_block(block[, format, opts]), and similar for inlines handles.

[rnwst]

Interesting approach. The functions pandoc.write_blocks and pandoc.write_block don't exist AFAIK. Instead, you would have to use pandoc.write(pandoc.Pandoc(blocks), 'markdown') and pandoc.write(pandoc.Pandoc({block}, 'markdown'), respectively.
You can use pandoc-lua-types for type checking.

[rnwst]

If you would like to use a Writer rather than a Filter as @tarleb sugested, there is an example in the documentation which uses a Filter inside of a Writer.