PaperCut Blog

Tech & DevTech tips

How to write Pandoc filters for PM Wiki in Lua

How to write Pandoc filters for PM Wiki in Lua

Here at Papercut, we often spend our Friday afternoon attending talks hosted by our fellow PaperCutters. You know, when we’re not all working from home because of a global pandemic.

A few months ago our resident IT geek Alec Clews was hosting a talk about Pandoc.

What’s Pandoc, you may ask, if you’re not a fellow techie? It’s a free and open-source document converter which is widely used as a writing tool, and as a basis for publishing workflows. It allows for a document to be converted from one form (e.g. Word) to another (e.g. HTML) while keeping original formatting intact.

As I sat there listening to Alec’s soothing and charming voice, I was thinking about a particular pain point of mine.

The problem

Whenever writing our KB (Knowledge Base) articles as a Papercut Support engineer, I’d run into a blocker with converting my writing into PM Wiki (the language used by our KB).

PM Wiki uses these really funky markup tags. To bolden something, you would format it like ' ' ' bold ' ' '. To italicize something, the formatting is, ' ' italics ' ' . Wanna do both? Then you’d format, ' ' ' ' ' both ' ' ' ' '. It’s annoying to read and to write.

Alec got me wondering. Could Pandoc convert a nicely formatted document like Word or Google Docs into the PM Wiki markup used by the KB?

Well, fortune favors the bold. So I decided to give it a try.

It didn’t work.

Well, that is, Pandoc didn’t have a native PM Wiki output option. However, I could create a custom “filter” using a language called Lua

That did work! 

The solution

I could use the filter to define how to parse the text out to PM Wiki.

With this foundation laid, I had streamlined how to create a KB.

Now, thanks to Pandoc and Lua, my process is simple:

  • Write and format the KB in Google Docs
  • Download and parse it through Pandoc to output the PM Wiki text
  • Copy and paste the new formatting into the KB
  • Make some minor tweaks before publishing  

Cool, so why did I do this? 

Well, the idea was to make life a little easier for myself and my fellow Support engineers. We’re passionate about helping our customers and we’re diligent in keeping our KB up to date to do so.

I just found those extra seconds of formatting for PM Wiki tedious and time-consuming, because it added up. It meant less time helping customers. 

So hopefully, this little workaround allows us to be more nimble and saves us some precious time to continue the Support side of things, without our day being monopolized by finicky formatting.

Comments