Module 22 Markdown documentation

Learning goals

  • How to document your projects with Markdown, and why doing so is so important.

 

This is a meta-tutorial for using Markdown, a “syntax” for writing beautiful reports with simple text files. This tutorial, which was written in Markdown, has been provided twice: first, as its formatted ‘book-ready’ form, and second as the raw text file used to write it.

What is Markdown?

Markdown lets you write documents formatted with fancy HTML (the main language used to create websites) without having to know how to write HTML code. Instead, you just need to know how to use a few common symbols.

Why?

Markdown was created because most data scientists used to document their code and data projects with simple text files (.txt). Text files are designed to be simple, so they have no special formatting: no nice fonts, no headings, no bold, no italics, no bullet lists. And, as a result of their simplicity, text files are (1) boring and (2) difficult to organize.

Markdown is the perfect solution: it translates a simple text file into a beautifully formatted report.

Recall that, in order for your research to be truly reproducible, you have to document your work thoroughly. Doing so requires two things: First, that you provide a detailed description of your work in a simple text file, and second, that your documentation be well-organized and enjoyably legible. Think about it: if your documentation is incomplete, impossible to navigate, and difficult to read, can you really say that your project is reproducible?

What can you do with Markdown?

First of all, Markdown …

  1. Lets you organize your report into sections and subsections.
  2. Lets you italicize and emphasize certain sections of your work.
  3. Lets you distinguish between normal text and code or filenames.
  4. Lets you write large chunks of code, like the one below.
# This is a large chunk of code. 
x <- 1:10
y <- 15:20
z <- x + y

Also, Markdown …

  • Lets you weave together your documentation with R code that actually runs (this is called RMarkdown, which is covered in the next module), opening up possibilities for automatic reporting and truly reproducible research publications.

  • Lets you produce publication-ready articles and books, since there is a world of open-source formatting templates available to you.

  • Lets you add hyperlinks.

  • Lets you type HTML code directly into the same document, if you want to.

  • Lets you include images, like the one below.

 

Common Markdown mistakes

  • When you try to make a section heading (e.g., ## New section), you forget to put a space between the hashtags and the name of the section.

  • When you try to begin a new paragraph, you don’t add two spaces at the end of your sentence. (Without those two spaces, Markdown will assume you are still working in the same paragraph.)

  • The same thing happens often when making a list. Without two spaces at the end of each item, the items might not get placed on new lines.

  • When you try to begin a new paragraph, you don’t add an empty line between your paragraphs.

Raw Markdown example

Below we provide the raw textfile we used to write the section above.

# `Markdown` documentation 

#### Learning goals {-}

- How to document your projects with `Markdown`, and why doing so is so important.

&nbsp;  

This is a **meta-tutorial** for using `Markdown`, a "syntax" for writing
*beautiful* reports with simple text files. This tutorial, which was written
in `Markdown`, has been provided twice: first, as its formatted 'book-ready' 
form, and second as the raw text file used to write it.  

## What is `Markdown`?  {-}  

`Markdown` lets you write documents formatted with fancy `HTML` (the main
language used to create websites) without having to know how to write `HTML`
code. Instead, you just need to know how to use a few common symbols. 

### Why? {-} 

`Markdown` was created because most data scientists used to document their
code and data projects with simple text files (`.txt`). Text files are designed
to be simple, so they have no special formatting: no nice fonts, no headings,
no bold, no italics, no bullet lists. And, as a result of their simplicity,
text files are (1) *boring* and (2) *difficult to organize*.  

`Markdown` is the perfect solution: it translates a simple text file into a
beautifully formatted report.  

Recall that, in order for your research to be truly reproducible, you have to
**document your work thoroughly**. Doing so requires two things: First, that
you provide a detailed description of your work in a simple text file, and
second, that your documentation be *well-organized* and *enjoyably legible*.
Think about it: if your documentation is incomplete, impossible to navigate,
and difficult to read, can you really say that your project is reproducible?

### What can you do with `Markdown`? {-}  

First of all, `Markdown` ...  

1. Lets you organize your report into sections and subsections.  
2. Lets you *italicize* and **emphasize** certain sections of your work. 
3. Lets you distinguish between normal text and `code` or `filenames`. 
4. Lets you write large chunks of code, like the one below. 

```
# This is a large chunk of code. 
x <- 1:10
y <- 15:20
z <- x + y
```

Also, `Markdown` ...  

- Lets you weave together your documentation with `R` code that
*actually runs* (this is called `RMarkdown`, which is covered
in the next module), opening up possibilities for automatic reporting
and truly reproducible research publications.  

- Lets you produce publication-ready articles and books, since there is a
world of open-source formatting templates available to you.  

- Lets you add [hyperlinks](https://www.markdownguide.org/getting-started/).  

- Lets you type `HTML` code directly into the same document, 
<font color='red'><b>if you want to</b></font>. 

- Lets you include images, like the one below.  

<center>
![](img/markdown-dogs.jpeg){width=50%}
</center>

&nbsp;  

#### Common `Markdown` mistakes {-}

- When you try to make a section heading (e.g., `## New section`),
you forget to put a space between the hashtags and the name of the section.  

- When you try to begin a new paragraph, you don't add *two spaces*
at the end of your sentence. (Without those two spaces, `Markdown`
will assume you are still working in the same paragraph.) 

- The same thing happens often when making a list. Without *two spaces*
at the end of each item, the items might not get placed on new lines.  

- When you try to begin a new paragraph, you don't add an empty line
between your paragraphs.

Exercises

Open a new, blank Markdown document:

1. In RStudio, go to the top left dropbown menu for making a new file (look for the green plus sign.)

2. Select “Text File”

3. Save this text file as test.md.

The prefix, .md, specifies that this text file should be interpreted as a Markdown file. Once you save the file, you should see some new options appear, one of which is preview.

4. At the top of your test.md file, write: # Title

5. Click the Preview button and see if a Markdown file is produced.

 

Make your own Markdown:
Use the Markdown example above, which you can compare to the formatted version at the top of this module, to figure out how to add the following elements to your document.

Use the Preview button to test if your entries are doing what you want them to.

6. Write a silly sentence.

7. Make a word in that sentence italicized.

8. Make a word in that sentence boldface.

9. Add the first section to your document. Name it whatever you want.

10. Add a sentence in this new section, formatting one of its words as a piece of code.

11. Start a new paragraph and add another sentence.

12. Start a third paragraph and add vertical space between it and the previous paragraph.

13. Add a multi-line chunk of code.

14. Download a silly meme from the internet and add it to your document. (Hint: you will have to place that image file in the same folder as your Markdown file.)

15. Add another subsection to the subsection you are working in. Name it “Grocery List”.

16. Type out an enumerated grocery list.

17. Add another subsection, this time at the same hierarchichal level as the one you created in step 9. Name it “Bucket List”.

18. Create a bullet list of things you want to accomplish before you die.

19. Make one of your list items act as a link to another website.

 

Update your Git repo README with Markdown

This will be a review of both Markdown and Git!

20. Navigate to your GitHub repo online.

21. If you have not yet added a README file to your repo, click on the button that generates one for you.

22. Click on the file to edit it.

23. Add Markdown to your README, showcasing the tricks you haved learned in this exercise thus far. Preview your changes as you go and make sure everything looks how you intended.

24. Commit your changes and check out your README on the homepage of your repo.

 

Make a Markdown CV

It is increasingly common for data scientists to have a Markdown version of their CV posted as its own page connected to their GitHub profile. Check out these examples:

Maintaining your CV this way can be very efficient. It is easy to format and easy to update. And, most importantly, rather than have various versions of your CV on your computer or in GoogleDrive, you can just share a link to your live, published CV. What better way to demonstrate your skillset in reproducible, professional-quality research?

25. Use the instructions provided here to create a new repo for your CV, type up your CV in Markdown, and publish it for free on GitHub Pages.

This will also be a review of both Markdown and Git!