Mastering Master Documents with Pandoc – Part 1
Why master documents, and why Pandoc?
Unless you’re an enthusiastic Wikipedia editor, you probably don’t have a lot to do with Markdown. Online educators and learning technologists tend to come in two types: those who prefer WYSIWYG editors and have a hard time visualising *this* as this, and those who are comfortable with markup languages and would prefer something more sophisticated, like <em>this</em> or even \textit{this}. But as Stuart Mealor pointed out, Markdown is a “hidden treasure”.
If your work involves writing documents in different formats, and especially if it involves writing the same document for different formats, you need some kind of master document system. This was brought home to me recently when I was asked to write a new Moodle guide for our staff. I started off in LibreOffice since that is what I write most things in, and I thought it would be easy to produce PDFs if needed. Unfortunately, my boss then said that we needed it in Moodle Book format. Now you can paste content from Word or LibreOffice Writer into the Moodle editor and it will work out OK in the end, but if you are dealing with long documents with graphics and complex formatting, you will spend a lot of time tweaking. (There are Moodle plugins to make Word import easier, but that’s for another article, maybe.) In the end, though, I managed to get everything into a Moodle book. Some time later, I was told that we also need a PDF version, but unfortunately by that time the Moodle version had evolved away from my LibreOffice original, so I couldn’t just click “Export as PDF.” Moodle Book has an option to export to PDF, but the result does not look very nice, and certainly didn’t meet our school’s formatting requirements for branding and accessibility. This was the moment when I decided (belatedly) that I needed a master document system.
Given that a master document needs to produce a number of different documents in different formats, it has a number of different requirements.
- It has to be in a form that file converters can handle easily.
- It needs to be able to indicate any formatting that you could want in any kind of document.
- When formatting is not available in the target document format, it needs to degrade gracefully (i.e., not mess up the layout too much).
- It should be easy to read in the source format.
- Because different people with different skills may be editing the same master document, the markup language should not be hard to learn.
- It should be easy to perform bulk operations (e.g,, merge several documents into one, find-replace over several documents).
- It should not be tied to one particular editor or operating system.
Now it’s clear that these aren’t all 100% compatible; for example, you can specify formatting to an insane degree with TeX, but it is a mystery to the uninitiated. Markdown, in contrast, is really easy to read and write, but its formatting options are severely limited. This is where Pandoc comes in.
Pandoc uses Markdown as a lingua franca for generating documents in over forty different formats, notable among which are:
- HTML
- Word
- OpenOffice/LibreOffice Writer
- EPUB
- Powerpoint
- CSV
Because clean input means clean output, you can also use the files you have generated as a stepping stone to something else; e.g., opening CSV files in Excel, or pasting HTML into Moodle.
So how does this work? Once you have a master document in Markdown and Pandoc downloaded and installed on your Windows, Linux, Chrome or macOS system, you just need to open a terminal and type something like
pandoc userguide_master.md -s -o userguide.html and your master document has been converted to clean, if rather plain HTML (the -s is for a standalone page – if you just want something you can paste into Moodle or another HTML document, leave it out). If you want a PDF document, then pandoc userguide_master.md -o userguide.pdf will do the trick (though you need to have LaTeX installed for this). Pandoc will guess the desired format from the file extension, but if you want, you can also specify it.
Now I did say "plain" HTML, and the PDF output is classy (because of LaTeX) but vanilla. But the beauty of Pandoc is that you have an arsenal of tools for precision formatting, from HTML tags to Word templates. In the next part, I’ll look into this in detail, but if you can’t wait, go straight to the Pandoc website and dive in.
- Singing with Suno – 2nd April 2024
- Documind: Chatting with Your PDFs – 2nd February 2024
- Using Moodle Checklists – 2nd January 2024
Pingback: Mastering Master Documents with Pandoc - Part 2 - ElearningWorld.org
Great post Robin, and very interesting.
I have only used basic Markdown within Moodle, and MoodleDocs, Wikipedia etc.
But I can certainly see how the ability to easily create a single text document, and then output it in various formats can save a lot of time, and provide a great amount of flexibility for online learning resources.