(R)Markdown for archaeology

One of my last posts was about LaTeX and why I think it’s a great tool. Confession time: Most of the time I write in Markdown nowadays. Why’s that?

First things first:

What is Markdown?

Markdown is another markup language (markup, markdown, you know 😉 ), in which one uses certain signs in plain text to mark how these passages should look like in the end document. For example, we use the hashtag # to demarcate headings and their level (# is the highest level, ## second level heading, ### third level heading). Or, we can use two stars to make text **bold** and underscores to write it in _italics_.

As for LaTeX there are a number of different editors one can use for writing Markdown and which show what the output will look like, e.g. MarkText, Zettlr or Texts. Markdown has been integrated into a number of programs and for example is often at the back of note taking programs, such as Logseq or Obsidian.

Each Markdown document starts with a so called “YAML-header”, in which we can specify metadata: What’s the title of this document, who created it, on which date… In some more elaborate set ups we can add abstracts or key words as well. Also, in the YAML-header we define some details of the output, e.g. whether there will be a table of contents, what kind of document we will have after rendering and after which template it will be modeled. An extra program, called pandoc, handles the rendering process. It is able to not just create pdf files, like LaTeX, but also html and docx files.

This is one of the reasons, why I use markdown a lot: When I write an article, a lot of editors don’t want me to submit a perfectly set pdf, but rather a docx-file, because they will do the setting themselves. Also I can easily present the same content in a different format to another audience, e.g. as an html web page.

But of course there are:

More reasons to use markdown

As I said, I mostly use markdown nowadays and I’ve got more reasons than the one mentioned above. Here they come:

Rmarkdown for the win!

The second, most important reason, is, it is easy to integrate R code into markdown by using Rmarkdown. Any text editor can read Rmarkdown files (*.Rmd), but I use Rstudio as my coding environment for R. In the Rmd I can mark certain areas in the text as being R code, by using these symbols:

 ```{r code_chunk_label}
here I write the code
```

The code will be rendered together with my whole document, to produce the graphs or outputs I want! This means, I have one document, in which there is the code and text (together!) and after the rendering, my whole article is done — the images are in the place, where I want them, the headings are headings as I’ve marked them.

I can even add citation:

Easy citation integration

Third reason why this is so cool: I can use a zotero library and add my citations to the document, while I write it. When I compose my paper in Rstudio 1.4, there is even a visual editor, which searches through my zotero library when I start writing the label of the paper I would like to cite here. This is so comfortable to use! Just as I described for the LaTeX-article, the bibliography will be created for me in the style I choose. For this I need a *.csl-file (citation style language) to enable the wanted transformation. Zotero offers a huge repository of csl-files just for this purpose. I’m sure you’ll find the one describing the style you need!

Easy project management

Admittedly, that’s not a markdown thing, not even a Rmarkdown feature, but rather an Rstudio feature. Rstudio also offers a project management system. So, Rstudio projects (*.Rproj) save the environment under which you write your code. I can create a project using, e.g. the package rrtools, which will create a folder structure and templates for me to use, which will help me organise my data, text, code and figures for a paper. It guides me through the process of creating metadata, a README, sets up the project with git, asks me to give a license to my code… all in all a great tool for Open Science!

Examples how I use Markdown

I can use Markdown and RMarkdown together with github to create webpages, e.g. for teaching R. A “bit” more elaborate is the website of the Special Interest Group Scientific Scripting Languages in Archaeology, but it also relies on Markdown a lot.

I’ve used it to create slides. e.g. for a tutorial on hdbscan (rendered html version here).

Here is an example of an Rproject, where I wrote the article in Rmarkdown.

Together with others I’ve used github to write this article on software reviews completely in Markdown.

So you can see, it is very versatile and useful. But is it “better” than LaTeX?

Comparison to LaTeX

You may have noticed, that a lot of the reasons I gave why Markdown is great, are the same reasons as the ones why LaTeX is great. So how do they compare?

I feel, Markdown is easier. One quote by Ben Markwick kinda stuck with me

It just needs less keystrokes.

Ben Marwick

And yeah, where I say “\chapter{}” in LaTeX it is “## ” in Markdown, so that is a plus.

On the other hand there are a lot less tweaking possibilities. This means if I have a specific layout in mind, which I would like to create (e.g. for CVs, catalogues or similar), I totally recommend using LaTeX not Markdown. For most articles, though, I’m not the one responsible for layout and I will save time by not focusing on it, which I am wont to do in LaTeX.

A nice thing is: Markdown can integrate LaTeX if needed (e.g. for mathematical notations)!

Both Markup languages are great for github or gitlab integration because in the end their files are just *.txt files, that can easily be tracked by version control systems such as git.

Both are easy on your system because of the small size of the files. You should be aware though, that you will always need the pandoc and latex conversion programs to create the output anew, should you want to change something in the old files.

So, what do you think? Do you use markup languages? Which one do you prefer? Do you have other reasons for using Markdown (or LaTeX?)? Let me know!