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

It is a great markup language especially for: Documentation, Creating websites, Project ReadMe files, GitHub Issues, GitHub Pull Requests, comments, among other things. One of the cool features of Markdown is that it can be used inside html blocks and html tags (excluding some) within a Markdown file.

If you’re already familiar with Markdown, this article will serve as a refresher as well as a quick start guide for beginners.

Heading

Just like HTML, Markdown heading can be written up to H6

Markdown:

Heading 1         # H1
Heading 2        ## H2
Heading 3       ### H3
...             ...
Heading 6    ###### H6

Preview:

H1

H2

H3

…

H6

Font Emphasis

Fonts can be italicized, bold with asterisk (*)

Markdown:

Italic          *Italicized Text*
Bold            **Bold Text**

Preview:

Italicized Text
Bold Text

Task List

Checkboxes for tasks list can easily be created with third brackets “- [ ]”

Markdown:

Checkbox            - [ ] Checkbox
Checkbox Ticked     - [x] Checkbox Ticked
Strikethrough       - ~~~Strikethrough Text~~~

Preview:

• Checkbox
• Checkbox Ticked
• ~Strikethrough Text~

Lists

Two types of lists can be created: Unordered List (Bulleted Points) and Ordered List (Numbered Points).

Markdown:

Ordered List            1. First Item
                        1. Second Item
                        1. Third Item

Preview:

1. First Item
2. Second Item
3. Third Item

N.B.: As you can see, I didn’t go for conventional way of writing ordered list (1., 2., 3., and so on). However, the Markdown previews the list in a numbered list. This is a simple trick, say if you need to rearrange any order you can simply cut it and paste it anywhere in the list, the Markdown will automatically rearrange the order. But if you use conventional way, it will become a bit tedious as you have to cut it, then change the corresponding numbers. A bit of hassle, isn’t it?

Table

Tables can be easily created in Markdown files, and the content of a cell can easily be aligned to left, center, or right as shown in the example.

Markdown:

Table           | Heading 1 |   Heading 2   | Heading 3 |
                |:----------|:-------------:|----------:|
                | col 1 is  |  left-aligned |  $10000   |
                | col 2 is  |    centered   |  $12000   |
                | col 3 is  | right-aligned |  $15000   |

Preview:

Code

Codes can be added as an inline code, and as a block of code as below.

Markdown:

Inline Code         `example of inline code`  

Block of Code       ```c++
                    string str = "Hello World";
                    cout << str;
                    ```

Preview:

example of inline code

string str = "Hello World";
cout << str;

N.B.: The name of the programming language is optional. If added, the syntax will be highlighted according to the language.

Diff

If it is required to show what changes have been made in the code, it can be done in a simple manner within a block.

Markdown:

Changes             ```diff
                    - string str = "Hello World";
                    - cout << str;
                    + int x = 78557;
                    + cout << x;
                    ```

Preview:

- string str = "Hello World";
- cout << str;
+ int x = 78557;
+ cout << x;

Links & Images

Links and images are quite similar syntax-wise.

Markdown:

Link            [A Soft Murmur](https://asoftmurmur.com/)

Image           ![An Apple](/assets/img/example.png "an apple")

Preview:

Link: A Soft Murmur

Image:

Quotes & Toggled Info

Quotes can be written with a “>” sign. To show information inside a toggled block the following syntax can be used.

Markdown:

Quotes          > This is an example quote

Toggled         <details>
                    <summary>Show More Info</summary>		
                    This is a sample toggle for showing more information inside "Show More Info".
                </details>

Preview:

This is an example quote

Highlight

Another interesting stuff about Markdown is to highlight a sentence or portion of a sentence.

The syntax is double equal sign (==) both before and after the portion, however, the double equal doesn't work on all Markdown files. Currently, Markdown on Typora, Obsidian, Quilt, and IA Writer supports the double equal sign for highlighting.

If highlight doesn’t work for double equal sign, we will use an alternative way of doing so.

Markdown:

Highlight           This ==word== is highlighted

Alternative         This <mark>word</mark> is highlighted

Preview:

This word is highlighted

Definition List & Horizontal Rule

Markdown:

Some Markdown processors allow to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the definition.

To create a horizontal rule, use three or more asterisks (***), dashes (—), or underscores (___) on a line by themselves.

Definition List         First Term
                        : This is an example definition of the first term.

Horizontal Rule         ***

Preview:

First Term

This is an example definition of the first term.

Below is a Horizontal Rule

Subscript & Superscript

Again, some of the Markdown processors support using one type of syntax for subscript, superscript and others support HTML tag.

Markdown:

Subscript           H~2~O
Alternative         H<sub>2</sub>O

Superscript         H^2^O
Alternative         H<sup>2</sup>O

Preview:

Subscript H₂O

Superscript H²O

Heading ID & Footnote

Many Markdown processors support custom IDs for headings — some Markdown processors automatically add them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.

Footnotes allow you to add notes and references without cluttering the body of the document. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets ([^1]). Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and text ([^1]: My footnote.). You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, block quotes, and tables.

Markdown:

Heading ID          #### My Great Heading {#custom-id}
Alternative         <h4 id="custom-id">My Great Heading</h4>

Footnote            Here's a simple footnote,[^2].

                    [^2]: This is the sample footnote.

Preview:

My Great Heading

Here’s a simple footnote,².

Here are some resources that are super helpful in getting started with Markdown.

• Markdown crash course in 15mins! Use on GitHub, Discord, Slack …
• Markdown Guide

References