In this blog you will learn the basics of Markdown and Markdown Files. These are in no particular order and some parts may seem obvious, while others less so. If you already know why its useful/already implement it, feel free to jump around. By the end you will learn:

  • What a Markdown File is
  • How to use Markdown Files to make amazing looking Notes without having to deal with a bunch of code
  • How to add rich features (e.g., linking to other Notes pages and sections, adding images, etc.) to your notes

Prerequisites:

  • None

What is Markdown

Markdown is a markup language. It is a super easy way to embedded structure when taking notes or documenting things. Markdown files are super common for taking notes, or perhaps most frequently, as README.md files for GitHub repos. This is because it has super simple syntax.

For example all these blogs were created with Markdown. To get started, make a file with the .md extension. Now any text you type will have a highlevel markup. So if you want to make headers like we have here just put # Title then have a line break and all the text underneath will be in that sub header. Similarly, you can create other headers with the following syntax:

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6

This syntax will show up as the following. In my case I have some extra CSS, so if you are fewing on my blog, then they might have slightly deferent sizes then the default.

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5
Heading level 6

Basically, Markdown is a way to allow you to focus on the notes or writing process to have a nice clean structure without dealing with the extra headache require to make them look really nice. Below are several simple/common things you will want to do in Markdown. But for more info visit the Markdown cheatsheet. Otherwise this post is mainly hear to let you get a sense of what markdown can do and for you enjoy your newfound skill! Don’t forget the Extra Practice at the end.

One final piece of advice, while viewing the .md file you won’t see all the fancy formatting; however, most modern IDE (e.g., Rstudio, VScode, etc.) have either native or plugin support to allow you to view the full fancy version while typing, so be sure to look for those to see how things are coming along. Alternatively, there are several note taking apps that are built with markdown in mind so you can explore those as well. Some example include: SimpleNote, Inkdrop, and Notion, but there are many more.

Bold and Emphasis

Bold and italics are easy. To use them just add * around whatever you want to alter. For example, to bold (**bold**), italics (*italics*), bold and italics (***bold and italics***).

This is the feature I use the most. Here we can use the following structure for links:

[description](link)

But when I mean link, I don’t just mean a website… no, no, no. They can link to any file on your computer as well using its relative path. So say we had a Markdown file containing notes. I can link to that file from here with the following syntax:

I can link to that file from here with the following [syntax](notes.md)

But it gets even better, since that is a markdown file I can even link to a specific subsection. For example, say their was a subsubsection (level 3 header) titled lottery. Then I can specifically link to that with this syntax:

Linking to the [lottery section](notes.md#lottery)

Of course, since you can link to a file, you can also embed pictures and links.

[My personal website](https://dsambrano.com/)

My personal website

![Image Description](/assets/imgs/git_stages.png)

Image Description

Note the !. Also, you need to have the image in that folder with that name for it to show up.

To have better organization/reability, you can use reference style links. So anytime you would use the [text](link) syntax you can replace it with [text][ref-name]. And then add the following to the bottom of your file:

[ref-name]: LINK "INFORMATIVE TITLE: OPTIONAL"

This is nice because you can use the same link multiple times, and if you ever need to edit/change the links you dont have to find them in the text, you just know they are at the end, so you edit them once and all of them in the whole document are fixed. Finally, these reference style links can also be used to for all link types include imgs/section links.

Lists

list are as easy as a dash:

  • first
  • second
    • second a
    • second b
  • third
  • etc…
- first
- second
  - second a
  - second b
- third
- etc...

Numbered list work as well (notice you dont even need to number them correctly):

  1. first
  2. second
  3. third
1. first
1. second
1. third

Code

Finally, to get fancy formated code you can add ` around your text, e.g., `text`. If you want to have a big block of code, you can just add three ticks ```.

```python
# Example Python Code here
from pathlib import Path
my_file = Path("my_file.txt")
pi 3.14159
print(f"My is {pi}")
```

Notice after the first ```, you can add a LANGUAGE, to determine how the code should be highlighted.

Math Support

For the LaTeX fans out there most editors have either native or plugin support for $ style equations. So simpler to the code example above, you can use $ for inline equations and $$ for equation blocks, but unforuntately it is note native.

Extra Practice

Create a Markdown file describing all the main scientific/developmental decisions you made on your most recent project. For example, why did you select that specific stimulus vs another or why did you choose that framework/database type over another. Why that method?

Hint: Link to relevant artcles or to other markdown files containing notes you made.