How to add a page break before header automatically in pandoc

Question

I need to convert a markdown document into a Word document. I need it so that before each header there is a page break.

For example, here, a page break would be inserted before # Heading 1 and before # Heading 2 . I wouldn't mind if it skipped the very first one if there is no content before it in the document.

# Heading 1

Hello

# Heading 2

World

I have found this Lua filter , but, as far as I understand, it's just for Latex and it's not automatic.

I have tried to write a Lua script myself, but failed, because I do not understand well how pandoc works.

For example, I have tried returning a Para with the contents of the previous one + a page break from the Header function like this:

function Header(el)
    if el.level == 1 then
        local t = { pandoc.RawBlock('openxml', '<w:p><w:r><w:br w:type="page"/></w:r></w:p>'), el }
        return pandoc.Para(t)
    end
    return el
end

However, it just ends up wiping all of the headers. I have tried a few other alterations of the same idea, neither of which worked.

The trouble in Lua is mainly the fact that there is no static analysis and no Intellisense. I may be doing something completely inadequate in this code without any compiler errors and without even realising it.

Answer 1

I believe the following should fix that:

local pagebreak = '<w:p><w:r><w:br w:type="page"/></w:r></w:p>'
function Header(el)
    if el.level == 1 then
        -- return both the page break and the header as a list
        return { pandoc.RawBlock('openxml', pagebreak), el }
    end
    -- No `return el` needed, as not returning any value is the same as
    -- returning the original value.
end

The error reporting of pandoc during unmarshalling, ie, while retrieving objects from Lua, is not great, to say the least. Ideally, pandoc should report the type error that comes from wrapping a list of "blocks" in a Para , as that constructor should only accept "inlines".

In case you are curious: I'm working on fixing this by switching to a different marshalling strategy, see this PR . It's taking a while, but we'll get there.