Learn Markdown

Markdown is a lightweight markup language for creating formatted text using a plain-text editor.

Wikipedia

I have always wondered why in Github some repos have beautifully documented readme section. Therefore, I decided to learn to create .md files for my readmes and posts.

Markdown is widely used in various occasions, including Github readme.md, almost any post you see online and post in university forums, like ed.

HTML

We must note that md supports raw HTML, so we can use any standard HTML labels and even inline style attribute in .md files. This really comes in handy if you already learned HTML.

Headings

Markdown resembles HTML in many ways. First one being the expression of titles and headings.

In HTML we have:

1
2
3
4
5
6
<h1>This is an h1</h1>
<h2>This is an h2</h2>
<h3>This is an h3</h3>
<h4>This is an h4</h4>
<h5>This is an h5</h5>
<h6>This is an h6</h6>

showing six heading levels. In md we also have the same structure:

1
2
3
4
5
6
# Title (h1)
## Section (h2)
### Subsection (h3)
#### Details (h4)
##### Small Heading (h5)
###### Tiny Heading (h6)

In addition, we can create horizontal lines with:

1
2
3
* * *
_ _ _
- - -

Lists

Lists are often used in frontend developments, as in HTML.

In md we create lists(ordered and unordered) with “*, -, +” and numbers.

1
2
3
4
5
* List 1 (remember the indentation)
+ List 2
- List 3
1. List 4 Item 1
2. List 4 Item 2

And it also supports tick boxes with “[x]” (suprisingly the x means tick, lol):

  1. learned headings
  2. learned lists?

Break line

In HTML breaking a line simply needs a <br> label. But in md, it is a bit different.

Breaking a line in md typically need two enter or two space.
Observe:

1
2
3
First line

Second line

or

1
2
First line  (two spaces)
Second line

Both will be recognised as two separate lines.

Instead, using one enter will be interpreted as one space.

However, this is not always the case. As in lists, two enter will cause the second line to appear outside of the list item while two space will enable the second line to be inside the list item.

  1. Break inside the
list item.
  1. Break outside of the

list item

Code blocks

Code blocks can be created by including the codes in side three ` . 

1
console.log("Hello World");

And inline code blocks uses one ` Instead. Like print("Hello world") .

Another important thing is that we uses “" to prevent the character from acting upon its original purpose. Just like the ` above.

Reference

Md enables reference using >. It follows the same line breaking logic as in lists.

In addition, we can treat the reference block as individual and put new reference or lists in it. The effect looks like:

Reference

  1. Reference list
  2. Reference list

    Inner reference

    1
    >print("Inner code block. Just like a Russian matryoshaka doll!")

In HTML when we need to show links we use something like:

<a href="https://home.student.monash">monash student portal</a>
monash student portal

In md we can achieve the same objective using [] and (), where [] is used for link text and () is used for link address(url).

Observe:

[monash student portal](https://home.student.monash)

or 

1
2
[monash student portal][a]
[a]: https://home.student.monash

monash student portal

Same format applies to images. We only have to remember to put a ! in front of everything.

Observe:

![starry night](https://upload.wikimedia.org/wikipedia/commons/thumb/e/ea/Van_Gogh_-_Starry_Night_-_Google_Art_Project.jpg/960px-Van_Gogh_-_Starry_Night_-_Google_Art_Project.jpg)

starry night

However, you cannot change the image’s size or other styles with md syntax, so I recommend using HTML for this part.

Bonus: we can make the starry night image smaller in html.

Starry Night

Tables

In HTML we have <Table> label to create tables, and <tr> for each row, <th> for the header, and <td> for the data in the cell.

In md however, things are more intuitive with tables. We just draw the table with |.

For each row, we use | to separate each cell and type in the content between them:

1
2
3
| header 1 | header 2 | header 3 |
|-|-|-|
| cell 1 | cell 2 | cell 3 |
header 1 header 2 header 3
cell 1 cell 2 cell 3

But remember to put a row of - below the header, the interpreter uses this row to identify the table item. (the number of - doesn’t matter.)

On the other hand you can set the alignment of each cell with : in the special row.

  • |:--|: left align
  • |--:|: right align
  • |:--:|: center align

The table items also support embedding other components like code blocks, lists, etc.

Customization with HTML

As we briefly mentioned before, .md file supports raw HTML syntax, which makes it very adaptable to customization.

For example, using <u></u> tags to show underscore, using <i></i> to show italic, using <span style=""></span> to customize font, etc.

You can even embed videos from Youtube or Bilibili with iframe label:

In md, we also support adding

  • bold font with **bold** or __bold__.
  • italic with*italic* or _italic_.
  • strike-through with ~~strike-through~~.

Formulas and symbols

For those who desire using md for academic writing (I sincerely hope not), typing formulas and symbols are a very tricky part.
Thankfully, md supports math symbols for complex formulas, you only have to include them in $$(in blocks) or $(inline).

Obersve:
$$
E = mc^2
$$
and $E = mc^2$

Markdown and latex uses the same system for mathematical expressions, they can be found in

English version: https://rpruim.github.io/s341/S19/from-class/MathinRmd.html
Chinese version: https://zhuanlan.zhihu.com/p/450465546
Tips: your interpreter should enable mathjax to show formulas.

Personally, if the expression is too complicated, I would rather embed images of the formula using <img> label.

Emoji and Icon

Markdown supports emojis and icons. There are ways to insert them in .md files to make the document more interactive:

  • ✍️Copy and paste the desired icons.
    You can find almost all emojis in emojiall, just copy and paste them to your files.
  • ✍🏻Using Github style Emoji shortcodes.
    You can find the shortcodes in this page.
  • ✍🏾Using Unicode of emojis.
    You can find the unicode on unicode official website.