Conditional language for filtering markdown content in lua based on metadata

[dude-at-RA]

I'm sure other people have solved this problem; I'm curious how they've done it though.

We use pandoc (and extensive lua filtering) to convert markdown to various outputs.

We want to add conditional statements into the markdown body that allow us to check metadata values for whether to include that content in the output document. We pass metadata into the lua filters (via pandoc) and essentially 'touch' all the content in lua.

The obvious place I think makes sense is in the bracketed span and fenced div attribute sections. Something like:

[conditional content]{ global.metadata.variable="someVal" }

where the content is included if the attribute global.metadata.variable value equals someVal. If the attribute doesn't, the block is replaced with an empty set. The trick is formatting this condition such that it is HTML / XML compliant, but still easily human readable.

I have some ideas as to how to do it - stuff like:

• [conditional content]{ if.global.metadata.variable="someVal" }
• [conditional content]{ global.metadata.variable="?someVal?" }
• [conditional content]{ global.metadata.variable?="someVal" } (I'm pretty sure this is not HTML / XML compliant)
• [conditional content]{ ?global.metadata.variable="someVal" } (same for this)

But, there are probably better ways?

[jdutant]

A thought (not sure it's best):

[conditional content]{ onlyif="global.meta.variable=someVal"}

You need to pass two arguments to your conditional, a meta key (string) and its value (string). If meta keys are guaranteed not to contain '=' would do. If not you could provide a second syntax:

[conditional content]{ onlyif="global.meta.variable=someVal"}

It's not too difficult to extract the meta key with Lua patterns. One advantage is that a filter can easily target just those contents with conditional statements. A potential downside: not straightforwardly generalizable to other types of conditions (e.g. greater than for numbers), in case that turns out to be needed in the feature.

A more markdown-heavy approach would be to have two attributes:

[conditional content]{ ifmetavalue="global.meta.variable" equals="someVal"}

Advantages: easy to code (no pattern matching);l allows filters to pick up just the conditionals; straightforwardly extensible to other type of conditionals. Downsides: verbose; you may not like the 'equals' attribute.

[dude-at-RA]

An if / onlyif attribute is a clear way to express this. For now we can dictate the requirements for the conditional statement to make sure they are equality comparison only. I don't think there are any common JS libraries that care about if attributes in HTML; definitely not any that we use in our pipeline currently.

Thanks for the input!

[alerque]

Not to dissuade you, but just in case you don't know this would typically be a job for a templating system that pre-processes the content. My favorite such system is tera¹ but there are many others in this conceptual space such as handlebars², Jinja, etc. These tools allow for meta data to be passed into a template and generate output with conditional blocks, looping over data, multiple outputs, etc. For your application you would use one of these as a pre-processor to take your Markdown template and parse the conditional blocks, placeholders, etc. That would generate the full final content to then pass to Pandoc for further manipulation using Lua for transformation as necessary and finally conversion to other formats.

¹ _{There are several different CLI tools implementing this system as well as being baked into other applications such as the Zola static site generator}
² _{Again there are many implementations out there, this is just the main template language documentation with a reference JS implementation, but there is Rust and other tooling.}

[dude-at-RA]

Thanks for the recommendation!

I'm hesitant to use a templating system because our userbase (non-developers) are writing the markdown content that would need to contain the templating syntax. Preprocessing with a templating engine is probably a good long-term solution once our userbase (not techies / developers / etc) becomes more confident / familiar with markdown; I would much rather use a well-maintained templating platform than a bunch of locally developed Lua code.

Not a handlebars expert, but I think it would look like this?

---
audience: internal
---

# Intro

{{#if audience==internal}}

::: secret-info

Here's the access code to the door: 111111. 

:::

{{/if}}

[alerque]

Yes, having yet another thing to learn for your non-tech-savy users is certainly something to consider, although overloading properties vs. introducing a templating pre-processor may not be that much difference as far as what they have to learn, and some of the light weight templating language can be pretty easy to grok on reading (if not easy to remember/type right the first time).

I'm not a Handlebars expert either, but that looks about right. Obviously the audience value would probably come from external meta-data not a hard coded value in the same file, otherwise the conditional would be kind of pointless.

Perhaps as much so an issue as the additional thing to learn is your tooling support. If your users are using Markdown specific editors with syntax highlighting or tools to add attributes that might be a factor in what is easier to learn and implement. But in general I agree using the established tooling made for the job is better than a hand-rolled improvisation that overloads features (e.g. using attributes for conditionals).