How to redefine -top-level-division in pandoc for each constituent file separately? - text

Question

I have a bunch of .md constituent content files marked up with headers #, ##, etc.
I want to flexibly compile new documents, with constituent files unchanged but residing at different levels of ToC hierarchy of the final document.
For example:
In compiled-1.pdf, top-level header # Foo from constituent-1.md might end up as "Chapter Foo" --- no change to its level in hierarchy.
However, in compiled-2.pdf, the very same # Foo from the very same constituent-1.md might end up as "Section Foo" --- a demotion to level 2 in the ToC hierarchy of compiled-2.pdf.
In each constituent .md file the top level header is always # and each constituent .md file is always treated as a whole indivisible unit. Therefore, all of a constituent file's headers are to be demoted by the same factor. Also, a constituent file's headers are never promoted.
I feel the problem has to do with re-setting -top-level-divison for each file. How to do it properly (using .yaml configs and make)?
But maybe a better way is to create for each final document a master file that establishes a hierarchy of constituent files with a combination of include ('constituent-1.md') etc. and define ('level', '1') etc. Such master file would then be pre-processed with m4 to search and replace # with ## or ### etc., according to each file's level, and then piped to pandoc.
What's the best approach?

Answer 1

I think these are the right ideas, but not the right tools. Instead of using m4, you might want to check out pandoc filters, especially the built-in Lua filters or the excellent panflute python package. These allow you to manipulate the actual document structure instead of just the text representation.
E.g., this Lua filter demotes all headers in a document:
function Header (header)
header.level = header.level + 1
return header
end
Similarly, you could define your own include statement based on code blocks:
```{include="FILENAME.md"}
```
Include with this filter:
function CodeBlock (cb)
if not cb.attributes.include then
return
end
local fh = io.open(cb.attributes.include)
local blocks = pandoc.read(fh:read('*a')).blocks
f:close()
return blocks
end
It is also possible to apply a filter to only a subset of blocks (requires a little hack):
local blocks = …
local div = pandoc.Div(blocks)
local filtered_blocks = pandoc.walk_block(div, YOUR_FILTER).content
You can combine and extend these building blocks to write your own filter and define your extensions. This way, one can have a main document which includes all your sub-files and shifts header levels as necessary.