Theses and Long Form Writing with Markdown

Published on by Nils Bühler, licensed under CC BY-NC-SA 4.0.

Many people are currently looking for alternatives to Microsoft Office Word. The most obvious option seems to be LibreOffice Writer – it does almost the same thing, but without the unnecessary (and surveillance-oriented) features and the licensing constraints of Word. For creating and formatting documents, adding citations, and inserting images, LibreOffice Writer is just as suitable as Microsoft's software. However, if you're already considering switching, why not also rethink your workflow? In this post, I want to present an alternative: Writing long form texts such as academic theses with the Markdown editor Zettlr.

Why it's worth considering alternatives to Microsoft Word and LibreOffice Writer

Word and other document editing programs operate on the so-called "What You See Is What You Get" (WYSIWYG) principle. These programs are actually a significant achievement. Instead of wrestling with sentence and formatting definitions that another program (or person) has to implement, you format your document yourself and can rely on the printed or PDF product looking (more or less) the same as the text in the program.

Text formatting, however, is a rather complex matter that is actually irrelevant when writing a lengthy text. When writing a book, thesis, or dissertation, it doesn't matter how the text looks until the final submission. Until then, the focus only needs to be on the content.

Because of this, WYSIWYG programs are not used in MINT fields, where complex formulas, graphics, and diagrams need to be displayed correctly. With programs like MS Word, this is hardly achievable. People in these disciplines thus often use LaTeX, which is commonly described as "What You See Is What You Asked For." There, you only edit plain text with clear formatting definitions for all those functions, graphs etc.

In the humanities, the presentation of individual complex elements usually doesn't matter. Here, the pure text is usually the focus. Because Word (supposedly) is so easy to use, it has paradoxically become the standard program for the creation of texts, even though its central function is actually the formatting of text.

Now that the call for switching to free and open source programs is so strong, people from MINT fields often suggest to humanities scholars to use LaTeX. I don't hold much of this view, as LaTeX is completely overkill for plain text writing, and even if you have programming experience, it's too complicated to use for this rather simple purpose. In principle however, these people are correct: Writing in Word or Writer is not the best option available.

WYSIWYG are designed to help you format a single document. Even if that is the main goal of writing a long form text, it is cumbersome to let all the work take place in one huge document. At some point, this single document is going to be to big to handle, and everyone who opened a 300 page file in Word will know that you can spend your time on more important things. Many people then split their monster file into parts, which need to be merged again in the end. What follows is a formatting nightmare right before the deadline, because maybe in one of those files, the formatting is a bit different in the others, creating a hot mess of a document.

The Best of Both Worlds: Well-designed Markdown Editors With Citation Functionality

There is a solution between those two extremes. You don't have to learn all those formatting definitions in LaTeX or deal with the error prone and cumbersome formatting configurations in Word or Writer. I am talking about modern Markdown editors, in which you can write plain text in a nicely designed interface with the option of exporting it to a whole range of formats.

A quick note on Mardown: This is a simple text encoding system, which you might have already seen as the text generated by LLM-based chatbots before it gets properly formatted. I have written a bit more about Markdown on my page on digital workflows. Just to give you an idea:

You will pick these rules up quite quickly.

Over the last few years, a number of well-designed Markdown editors have been developed, which make working in Markdown smooth and efficient. The internet is full of these apps, some of which you can use directly in the web browser. You can try them out easily, as the files produced will all be in Markdown and can, of course, be used by the other programs as well. I wrote my whole doctoral dissertation in the Markdown editor Zettlr and I will stick to it. It's open source and does only what I want it to do for writing.

Academic Writing with Zettlr

In its basic functions (writing in Markdown), Zettlr is the same as the other Markdown editors, but it has some additional funtionality which make it very attractive for academic writing. It is, e.g., very well integrated with the citation management program Zotero.

With a simple shortcut (typing the letter @), you can open a drop down menu to select a source from your Zotero database. It then inserts a citation key (as generated by Zotero with the BetterBibLaTeX plugin) which can also be used by other programs. In the right side pane, all cited sources are listed. So far so good, this could also be done in Word/Writer.

What makes Zettlr so valuable for me is its capability to navigate between and link multiple files of one project. I'm not talking about creating a knowledge database (more on that in the text linked above), but simply about the way Zettlr makes splitting a text into multiple files and then merging them together later so much easier.

You can open a file directory as a project to the left pane of Zettlr, where all Markdown files within that folder are listed. You can open them to tabs or in split screen, making it much easier to have that one section in chapter three and that definition in the introduction open while writing in chapter 7.

These folders can be assigned a project function, allowing you to export all files marked as relevant to be exported with one click. In order to do that, Zettlr uses the code library Pandoc, which translates texts between all kinds of file formats. In that way, you can have one source of texts (your markdown files) and as many output formats as you like.

You can link to other files, which is valuable of you want to reference other chapters. Zettlr keeps the chapter titles and numbers up to date. (This functionality is mostly meant to make your Zettlr files into a zettelkasten. This is great, but for zettelkasten functionality I still prefer Obsidian.)

Potential for Improvement

While I am very enthusiastic about Zettlr, I do see some room for improvement. It's important to keep in mind that the program is still relatively new and is primarily developed by its creator, Hendrik Erz, with a small team of two developers.

The export function is not yet fully mature for widespread use. Pandoc, which is used for exporting, is a powerful tool, but it's a command-line program, which can be a bit tricky to use, even if Zettlr moves the command composing under the hood for most purposes. If you want to export to PDF, you need to define the formatting in LaTeX, which as I said has a learning curve. Although the Zettlr team is working on better integrations, the process is still somewhat complex.

To simplify this, I created a template document in the odt format (used by LibreOffice) for my dissertation. Using Zettlr, I exported my text to odt using Pandoc, and then converted it to PDF. (This went a lot more smoothly than it sounds, it really is just a click once you set it up intitially.) This approach had its advantages, as it allowed me to review page breaks and similar details before finalizing the document. This way, I only used LibreOffice for the final visual touch-up. Despite this, a simpler way to format PDFs would be welcome.

This does not mean, by the way, that I could have just used LibreOffice instead. The upsides were still there: Writing was hassle-free and without distraction and the export to odt made the formatting in the resulting document unified and easy. This saved me a lot of nerves in the last few days.

When Is a Switch to Markdown with Zettlr Worthwhile?

Leaving behind the familiar workflow with WYSIWYG programs is not easy. If all your previous work has been done in Word or LibreOffice Writer, it's a significant change. However, this decision is never final. Thanks to Pandoc, you can always export your text to odt or docx, where you can continue working as usual. Therefore, there's no real reason to hesitate when starting a new writing project. It's worth trying out Markdown with Zettlr from the beginning.

Things are different if you're already in the middle of a project. Theoretically, you can work backwards with Pandoc by converting a docx file to Markdown. It's also not impossible to transfer citations so that you can continue working in Zettlr. However, this process is quite complex. If you can handle the effort of re-entering citations, it's simpler to just copy and paste your text into Zettlr.

Need More Information?

If you need more info about how to implement this in a productive workflow, have a look at my page about digital workflows in the humanities. Zettlr's homepage has a nice introduction to Markdown. Also, feel free to get in touch if you want to learn more from my experiences!