Getting Started with Markdown and RStudio
By: Guglielmo Feis
Tags: Digital Humanities, Programming, Markdown, Workflow, Technology

Besides the programming language(s) of your choice (and duties), Markdown is a markup (notice the pun) language you need to know. In fact, most of readme files on GitHub presenting the instructions of your code are written in Markdown. And Jupyter Notebooks or Google Colab text fields are written in markdown.

TL;DR: If there’s text around in programming, that’s markdown.

[Superheroes read Markdown readmes as well. Photo by Road Trip with Raj on Unsplash]

Markdown Basics

Markdown is an easy markup language (think HTML). We type something to get some formatting. The basics are supersimple.

If you want to add sections, you number them with a ‘#’. The more you add, the deeper you are going into the sections. So ‘###’ is header3 in HTML or 1.1.1 if you want numbered sections. (There are further options to set this).

Italics is done using ‘*’ as a “tag”. Bold is two stars ‘**’.

Lists are created adding a new line and then listing items either with ‘-’ or numbers followed by a point (1., 2., ..). And that’s it, basically. Here’s a full cheatshit with markdown (tables are nice!).

(Oh, yes, html links automatically take the reference. If you want to add clickable text to the link the syntax is ‘[text to show](link to refer to)’.)

To write markdown all you need is a text editor, but if you need to produce reports, write papers or other forms of more structured text, it is worth to write markdown using a different environment, like RStudio.

Markdown through RStudio: The Benefits for Academics

Writing markdown through Rstudio offers academics and people working with texts and data a super advantage: the work can be exported as .pdf, .html and .doc. Further, you can control the form of the output, whether its a regular text or a slideshow.

Besides that, RStudio offers you further tools like control on the bibliography that you can print in different styles by changing a parameter (think LaTeX). Plus you get themes and layouts.

Installing RStudio

RStudio is Integrated Development Environment (IDE for short) for R. R is a programming language on its own, used mainly for statistics. Using R you can plot data and analyze them, but we are not interested in that here. Of course you are encouraged to explore the strenghts of R.

We are using RStudio as an enhanced text editor. With RStudio we can easily type our markdown text, and then format it and manage the bibliographhy through specific commands. If you have any experience with LaTeX, the visual impact of RStudio won’t surprise you that much.

First things first, head over to RStudio download section: https://rstudio.com/products/rstudio/download/. Then pick the relevant version for your system. It’s free (there are also paid versions offering more features).

Once you open your first RStudio session go to ‘File’ > ‘New File’ > ‘R Markdown’. Enter title and author and move forward. You can now see your environment. Most of it is the file you you are writing.

[Here we go with lo(l)-fi tutorial graphics]

Let’s briefly go through the main areas.

1. RStudio Open Docs Tab

This is where you navigate through your RStudio files. You may have more than one file opened at the same time, as you do in the browser. Everything is close by and visually organized. Think about working on different chapters in different tabs, then assemble the whole book thing from there. Now thing about doing this in Word. And cry.

2. RStudio Main Working Window

This is where you write your stuff. You have line numbers, which is nice if there should be some issue in type setting your figures, but mainly it’s your Word main page. If you look up in your document your have a preamble like LaTeX.

The preamble starts after three single line (like this ‘-’) and finishes again with three lines again. The preamble of this document looks like this:

---

title: “Rijeka”

author: “Guglielmo Feis”

date: “10/2/2020”

output:

html_document: default

pdf_document: default

---

HTML output is great to make ebooks and compiles faster. If you need a pdf, just replace the output with ‘pdf_document’. Use ‘word_document’.

(In the next section we’ll cover adding a little bit more of control to our file, like adding a table of content and adding a bibliography.)

3. RStudio Console

This is where you select the output you want to export to, choose a template if you want one, adjust table of contents setting as well as bibliography parts.

Below this main window you have the console, which you will call to install further packages (as you did in LaTeX).

RStudio Workflow and Installing New Packages

You may want to pause for a bit and maybe consider choosing a different theme or background (there’s a dark background). Go to ‘Tools’ > ‘Global Options’ > ‘Apparences’.

We are ready to go and start writing some Markdown. Nonetheless, to unleash the full potential of the tools there you may need to boost RStudio with additional resources. Here we briefly touch how to install them, so that you are free to go and add as much as you need to make your best possible work.

The console of RStudio is important. This is where you go if you want to edit your package and improve it (something similar to Python PIP install).

If you want to figure out what packages are installed you need to type ‘installed.package(“NAME OF THE PACKAGE”)’. RConsole is friendly.

It is a command line interface tool, so it may require some 15–20 minutes to interact with it, but it is friendly in telling what went wrong and sometimes it even suggests you your next move (for example: ‘You want me to do X, but in order to that I need Y. Please install Y by doing Z’. — If your colleagues are all as helpful as RStudio console then you’re lucky.)

Here are some further resources on R Packages and their installation.

[Printed RStudio outputs. Photo by Patrick Tomasso on Unsplash]

RStudio for Humanities (More Preamble Options)

As we already know, the preable is where you define all the settings of your document. Things like whether to print a table of contents and how to deal with section headings and numbering. Which style of bibliography do you prefer as well as general layouts.

Here’s a list of some powerful options you have to add below the output choice:

toc: TRUE (or yes) — shows toc; toc_depth: value — decide how deep the toc will be; numbered_sections: TRUE — show numbers of section in the toc.

Guess what you need to do to avoid showing the table of content or the numbers.

As an exercise, write the preamble to that produces a document called ‘RStudio is amazing and I know why’ where you are the author and date is the current day. You want to print the table of contents without numbers and you want to show sections, subsections and sub-subsections.

Ok, below is the code.

Ready?

---

title: "RStudio is amazing and I know why"

author: "Enter your name"

date: "enter today's date"

output:

html_document:

toc: TRUE

toc_depth: 3

numbered_sections: FALSE

---

(Yes, if you do not want something you use either FALSE or no.)

Beware about the formatting. You’re better of nesting all the options and parameters. Should you have knitting errors

Setting the Bibliography

In the Humanieties a huge amount of time is spent (wasted?) in the “submit-wait-blame reviewer 2-change the formatting-submit elsewhere” cycle.

The present set up can’t grant you faster responses or better reviews, but it can save you type checking and changes commas and parantheses managment when a journal wants you to check that “The article follows author guidance for bibliographies” tick. (Assuming the journal is able to translate its preferences in some sort of standard or known bib style).

To add a bibliography all we need to do is to add a:

bibliography parameter in the preamble.

Then we need to specify the formatting style (of course you realized that the information across the different apa, author date, full cite, chicago etc., references are always the same, still displayed in different ways).

This is fine and easy but we need to have a file with bib entries, stored in a way that can be automatically managed to different formats. The file format is ‘.bib’. You can easily write it with a text editor, but it takes time.

It is worth knowing how .bib files are writen and what they look like, so that you can tweak them efficiently if you need it. Here’s an explanation of .bib files.

Ok, now we have a basic understanding of .bib files. Our goal is to have a .bib file to feed to our preamble. Then, through the preamble, we will manage our bibliographic details and we are going to quote the references throught our main document.

To produce the .bib file we can use a tool like Mendeley or JabRef.

[Nope, not this Mendel… Photo by Mikołaj Idziak on Unsplash]

The tools allow you to manage a bibliography. You can import data you downloaded from various internet databases, you can browse articles and insert them, you can modify your entries, etc. Both software have browser plugins to allow you to insert bibliodata from the pages you visit.

You can workout a comparison on your own. Mendeley has Springer involved with it. JabRef is open source, you can see the code and solve issues on GitHub (it’s Java based).

(I sorted out an issue with a huge .bib file using JabRef. I then build a new bib base with Mendeley relying on the plug-in mainly, which worked decently enough. The Mendeley-Word integration worked but not that smoothly.)

Bibliography Template Example

Ok, let’s write a working preamble. We add the bibliography field and define a style with ‘csl’ (which stands for citation style language, quite spot on, isn’t it?).

---

title: "RStudio Bib Demo Cas"

author: "Guglielmo"

date: "9/10/2019"

output:

pdf_document: default

bibliography: demobib.bib

csl: europeanjournal.csl

abstract: Demo showing RStudio bib management

---

In addition to our ordinary parameters we add the ‘bibliography’ field. What follows is the name of the file containing the bibliography (guess what? You’d better put that file in the same folder of your main Markdown file).

You can also specify a certain csl, i.e. the citation style language, feel free to read more here about how that works. Just google the csl you need. Different csl means a different look of the references throught the document. You just need to find and type in the right csl, not change every dot.

Citing Entries

To cite the entries in the bibliography you need to use @syntax. Suppose there’s a file called ‘myamazing2020paper’ in your .bib file. To quote it, just type @myamazing2020paper and the reference will show up as required. It could be a footnote displaying (Yourname, 2020) or a ‘Yourname (2020)’ or ‘(Yourname 2020)’. It all depends on the csl.

At the end you’ll have a list of the files in the bibliography (be sure to add some sort of ‘# References’ section at the end).

Here a few links for more bib-related stuff:

— More Info on Citations Styles

— More Info on Bib Styles

[Nicely ordered formatted references. Photo by Susan Yin on Unsplash]

Newlines, Pagebreaks, Cross-references and further Text Divisions

You can add horizontal lines in your document using six consecutives ‘-’ or six consecutive ***** (wait, there were five before the parenthesis).

If you want to insert a pagebreak you have to consider the output you are using. If you are knitting into a pdf (using a tex), you can use the latex command

ewpage or \pagebreak.

If you need to add section references or similar you need to boost your markdown. The easiest option is to install the bookdown package. Once you do so, you can easily refer to sections of your work putting the name of the section between square brackets. See here for more. Bookdown is also usefull to have parts and chapters.

Creation of Tables

Markdown tables are easy to write. You just build the table out of | and -. To define cells are devided by ‘|’. To define a table structure you need to have a set of — under the main table call.

Like this:

| Column heading|

| ------------- | # use :---: for centered text, ---: for right text

| col value |

| another value |

| etc |

Note that you need at least 3 dashes separating each header cell. The outer pipes (|) are optional, but looks good. Also, the table will be made even if the pipes are not all vertically aligned. raw Markdown line up prettily. You can also use inline Markdown.

Adding Images

If you need to add images, the Markdown syntax is close that of the links. In fact the syntax is

‘![text of the image if you hover over it with the mouse, aka ‘alt text’](path to the image)’

Note that the where to find the image can be a url site or a file on your pc. In the latter case, be sure that you are inputing path names correctly. Practically: should you get an errror, try to change the slashes: ‘\’ with ‘/’.

However, note that if you are using RStudio to knit your document (and not, say, displaying some text on the internet), RStudio requires you to put the images in the same folder as your main Markdown document.

Cross Referencing

If you need to add section references or similar you need to boost your markdown. The easiest option is to install the bookdown package.

Once you do so, you can easily refer to sections of your work putting the name of the section between square brackets (more info, here).

Adding Code Block(s)

Another benefit or Markdown you have is that you can insert code blocks. The code can be Python code, R code (it’s RStudio we are using, after all) and much more. In fact RStudio supports SQL, Java, C++. What’s even better is that you can decide what to do with that code. You can display it or even run it.

In that way, if you want to include some fancy graphics that are code-based into your report, you can do that. Further, suppose you are writing a paper with some data. You change the data and all you have to do is refresh your code to have an updated plot. Forget the days of open Word, open Excel, update the chart, export it, remove the old one add the new one.

To create a code block allo you have to do is typing three backticks (```), ort ‘CTRL + ALT + I’.

Comparing this Setup with more Traditional Ones

After this dense exploration you may wonder why you have to switch to that setup rather than the standard Word-powered one. There’s a lot going on, I’ll limit it to a few bullets.

You can speed up the resubmit process . Change the csl and you’re done. No more years spent with fixing details in Word (been here, done that). You can do a bit of that with bib managing tools in Word but my experience with them over a 10 pages project becomes a nightmare. And it get worst if your worked is shared.

. Change the csl and you’re done. No more years spent with fixing details in Word (been here, done that). You can do a bit of that with bib managing tools in Word but my experience with them over a 10 pages project becomes a nightmare. And it get worst if your worked is shared. (The above leeds to a better planning for your journal trajectories. You’ll appreciate editors that know their preferences and can point you to the right bib style or csl. If they don’t know that they are probably an Island and not worth your time.)

You can export to all outputs . You’ll want HTML if you want to use Amazon Kindlegen and get a smooth transition to mobi format. You’d like to go from a pdf to a doc if you are unlucky and your nice latex-based Ph.D. dissertation falls pray of strange academic publishing standards (been here, hated that). Latex to Word is hard, here you have the Markdown layer that has all the features you need and is able to output in different ways.

. You’ll want HTML if you want to use Amazon Kindlegen and get a smooth transition to mobi format. You’d like to go from a pdf to a doc if you are unlucky and your nice latex-based Ph.D. dissertation falls pray of strange academic publishing standards (been here, hated that). Latex to Word is hard, here you have the Markdown layer that has all the features you need and is able to output in different ways. Given the success of GitHub and the issues with peer review and academic publishing (enter your favourite), we may envisage a day in which GitHub enters Humanities. Guess what is the language of text on GitHub.

The whole thing is free . Ask your Head of Department (if she knows it) how much your University spends on licenses. Translate this into semi-decent research fellows or imagine how a share of that may impact your university’s output. Then please take action and let me know about it.

. Ask your Head of Department (if she knows it) how much your University spends on licenses. Translate this into semi-decent research fellows or imagine how a share of that may impact your university’s output. Then please take action and let me know about it. Bonus point: Markdown looks more used-friendly than LaTeX if you’ve been a forum early adopter. It goes easy on \ and {}.

List of RStudio Shortcuts

Shortcuts can save a lot of time. With RStudio you are likely to be doing some operations quite a lot, so here are the relevant shortcuts:

open a new file: ‘ALT + F’ (then navigate on new file and choose what you need);

navigate across markdown files: ‘CTRL + ALT + left/right arrow’;

knit the document: ‘CTRL + ALT + K’;

instert code chunk ‘CTRL + ALT + I’.

The usual SHIFT, CTRL and ALT shortcuts to move around the text are still valid.

What’s More in RStudio

We are using RStudio as a Universal Typing Machine, but it offers even more. As we know already RStudio is way more than a cool markdown text editor. Besides its markdown capabilities and its R-based features RStudio also offers the following features you may want to check: