Guide to writing a Markdown

Hi all,

This is a basic guide to writing simple markdown documents that’ll be expected output going forward in your R code related homeworks.

First off, you can write your regular text just like I’m typing this. Spaces, indents, line-breaks etc are taken care off automatically. Cool, eh?

First off, makes sense to break a looong document into sections. Thus, we could have sections such as ‘Motivation’, ‘Problem background’, ‘Data’, ‘Model’, ‘Results’, ‘Discussion’ and ‘Conclusion’ for example.

However, sections, to be distinct, require headers. And headers in markdown are indicated using the hash (#) symbol as the first character of the line. One hash gives a big heading, two a slightly smaller one and so on until you have level six headings.

Motivation for this Analysis

The above is a level 3 heading. This below is a level 4 one.

Higher the level, smaller the heading font.

Problem Context and Formulation

And so on. All good, I hope?

Alrite. We typically should insert code-chunksinto our markdowns and knit them into the storyline.

Here’s how we can do code-chunks. Three back-apostrophes followed by an ‘r’ in curly braces at the beginning. And three back-strophes at the end.

plot(cars)

summary(cars)

##      speed           dist       
##  Min.   : 4.0   Min.   :  2.00  
##  1st Qu.:12.0   1st Qu.: 26.00  
##  Median :15.0   Median : 36.00  
##  Mean   :15.4   Mean   : 42.98  
##  3rd Qu.:19.0   3rd Qu.: 56.00  
##  Max.   :25.0   Max.   :120.00

Note knitR in Rstudio automatically takes any graphs, tables or figures you’ve built with your code, transform it into html and weave it into your markdown’s fabric. How cool is that?

BTW, ‘cars’ above is an inbuilt R dataset, doesn;t need to be loaded externally.

Oftentimes, we’d like to include external images into the markdown. There’re ways to do it - if it’s an online image that can be hot-linked, thensimply use the image URL like so below.

If its a pic in your local system, then I’d recommend uploading the image to an online photo-hosting site, and then hotlinking the image URL. Me, I use https://postimg.org which doesn’t even ask for logins.

Above, note I’m using traditional html tags to encode the image.

Then there’s emphasis etc that we’d like to put onto font.

Emphasis, aka italics, with asterisks or underscores before and after the target word or phrase.

Strong emphasis, aka bold, with two asterisks or two underscores before and after the target word or phrase.

Strikethrough uses two tildes before and after the target word or phrase.E.g., Scratch this.

Underline text with HTML u tag . See how easily regular html tags can be used within markdowns.

How to make lists?

Just write the items to be listed with a hyphen and sublist indents with one or two tabs, then hyphens.

• unordered item 1
• unordered item 2
  • unordered subitem 1
  • unordered subitem 2
• unordered item 3

1. ordered item 1
2. ordered item 2
3. ordered sub item 1
4. ordered item 2
5. ordered item 3

LaTex can be used to write mathematical operators

E.g., see below.

• Add:

• \(x + y\)

• Subtract:

• \(x - y\)

• Multiply
• \(x * y\)
• \(x \times y\)
• \(x . y\)
• Divide
• \(x / y\)
• \(x \div y\)

• \(\frac{x}{y}\)

• Relations
  • \(\pi \approx 3.14159\)
  • \({1 \over 0} \neq \inf\)
  • \(0 < x > 1\)
  • \(0 \leq x \geq 1\)
• Fractions
  • \(^1/_2\)
  • \(\frac{1}{2x}\)
  • \({3 \over 4}\)

• Power & Index

  • \(f(x) = x^2 - x^{1 \over \pi}\)

  • \(f(X,n) = X_n + X_{n-1}\)

Summary

To write a markdown, start with a notepad, copy the above code, edit as required and save as as ’*.Rmd’ file.

Then open it in Rstudio and to build your markdown, run knit HTML. You should have package knitr installed for this.

The figure below shows you the location of knit HTML in a ‘.Rmd’ file.

Hope this tutorial helped. Practise a few times, if new to this. Read the other links given on the relevant blogpost.

And happy storytelling with markdowns for your homeworks to come!

Sudhir