A Beginner’s Guide to Markdown

Howdy fellows!

I hope your learning are going well. Well mine too. If you remember while creating the repository on Github, we have initialized it with a file README.md. We know the actual motive of making this file. The file contains the information and details about our repository or project. But have you focused on the “.md” extension the file has. What does it mean? Why not “.txt” or “.html” or any other? The answer to all these questions lie in the word Markdown. This is only one use case which I mentioned, there are many more.

Markdown is a simple text-to-HTML conversion tool for web writers. The main ideology behind its architecture is to make its syntax more readable unlike in HTML code where it becomes messy with lot of tags. Though one thing to note down here is that Markdown is not a replacement of HTML. It’s not even close to it. It supports only a small subset of HTML tags. HTML is a publishing format while Markdown is a writing format. It is suitable only where the message can be conveyed in a simple plain text. Though one can use HTML tags along-with Markdown. Just make sure that block level elements like <p>, <div>, <table> are surrounded by blank lines and start and end of the tags should not be indented with any spaces or tabs.

I listen, you want to dive more into it. So what are we waiting for, let’s begin.

How to write Markdown

Headers

Markdown provides two styles for headers:

• Setext: Setext style headers are created for h1 and h2 level of heading by underlining the text by “=” (equal to) and “-“(hyphen)  respectively.
• atx: atx style headers are created for all levels of heading ie from h1 to h6 by starting the line with respective number of hashes(#). So, if you want to generate a level 2 heading, you must start the text by 2 hashes(#).

This is level 1 heading
=======================

This is level 2 heading
-----------------------

# This is also level 1 heading
## This is also level 2 heading
###### This is a level 6 heading

Make sure to give a space after each #.

Blockquotes

The blockquotes can be produced by writing the text after an angle bracket “>”. These can be nested one inside another. Just don’t forget to give a space after each angle bracket before start writing the text.

> This is a blockquote
>> This is a nested blockquote
>

Lists

Lists can be categorized into two categories ie

• Unordered list: These lists use the asterisks(*), pluses(+), hyphens(-) as list markers. We can use any one of these. For nested lists we need to indent the line with either 4 spaces or a tab.

Note:-Dots before the list markers are used to show the number of spaces.

* Vegetables
* Fruits
....* Apple
....* Mango
+ Grocery
....- Milk
....- Spices

• Ordered list: These lists use regular numbers followed by periods as list markers. These can also be nested with same rule applied.

1. Red
2. Yellow
98. Blue
....1. Skyblue
....2. Darkblue
4. White

In above example, the third list marker is a random number, but it will be shown in sequence which implies that ordered list are independent of number we give at the time of writing Markdown.

Links

Markdown supports three styles for creating links which are as follows:

• Inline links: In Inline links parentheses are used to enclose the link just after the link text which is delimited inside the square brackets. We also may include the title attribute in the link. For eg

This is a [link text](https://www.example.com "title")

• Reference links: These links allow us to refer to actual links by names, which we can define anywhere throughout our document. The same pattern is used here to delimit the link text ie we enclose it in square brackets. These links are often used when we want to refer to a local resource.

This link corresponds to [Google][1] and this to [Yahoo][2]
[1]: https://www.google.com "title1"
[2]: https://www.yahoo.com "title2"

As we can see, we can give title in this case also after the link. Also, the link name we give can contain numbers, letters or spaces but they are case insensitive which means that [Google]≡[google].

• Automatic links: If we want to give the link as the text also. Then we enclose it in angular brackets(< >).

<https://www.google.com>

Images

Markdown image syntax is very similar to that of links. The only difference which distinguishes it from links is the exclamation mark (!) which we give at the very beginning of the syntax. Here also we have two different syntax to insert images:

• Inline Style
• Reference Style

These are same as links, an example would be sufficient to understand the difference.

![alt-text](path/to/image "Title")

![alt-text][id]
[id]: path/to/image "Title"

Here alt-text is short for alternative text which appears only when the image is unable to load itself.

Code

Many times we need to insert the code of a particular language as it is. This can be inline or a block of code. Markdown provides an elegant way to deal with both the cases.

To put the code inline, wrap the corresponding text in backticks (` `).

This is an example of `inline` code

To specify a block of code, indent every line of code with four spaces or one tab.

....for i in range(1,4):
....    for j in range(4,i):
....        print("*")
....    print()

In both inline and block of code, the special characters get escaped automatically.

We can put a block of code surrounded by three backticks, which would do syntax highlighting also. So, above example can also be written as:

```for i in range(1,4):
        for j in range(4,i):
             print("*")
        print()```

Text-Formatting

Very often we require to format a piece of text according to requirement, for eg sometimes we need to emphasize a word or a sentence. So to achieve such things, Markdown has an easy and simple method.

• To emphasize a word or a group of words, surround the text by double asterisks or underscores.
• To italicize a word or group of words, surround the text by single asterisks or underscores.
• To get both the emphasized and italicized format, surround the text with triple asterisks or underscores.
• To get a strike-through pattern, wrap the text with two tildes(~) and to highlight the text use double equal to sign(=) around the word.

*I am italicized*
**I am bold or emphasized**
***I am both bold and italicized***
~~Strike through~~
==I am highlighted==

Note:- Strike-through and highlight are the extended features of Markdown. They might not work in some Markdown editors.

Horizontal Lines

To get a horizontal line using Markdown syntax, we place three or more either hyphens, asterisks or underscores in a blank line.

***

Above syntax would produce a straight horizontal line on your page.

Escaping

To escape special letters or characters, we use a backslash(\) before it. So for eg if you want to print something like this:

2010. The Earth destroys

But if you write the exact same text, this would not give the desired output. Can you guess why? It’s because, the number “2010.” would be treated as an ordered list marker which would make it a list element. So to get desired output, we need to escape the period. We would need to write something like this

2010\. The Earth destroys

Tables

Though tables are not the core features of Markdown. But we can build tables using Markdown.

Name | Enrollment No. | Section
--- | --- | --- 
Prashant Sharma | 04415603116 | S9
Shiva Saxena | 05815603116 | T19

In above example, we have used pipe(|) symbol to seperate the columns. There must be atleast three dashes seperating each header cell. Though it might not look like the actual table now, but it would show a proper table structure.

Note:- This might not work in some Markdown editors like ReText, since it is an extended feature of Markdown.

Footnotes

This is another extended feature of Markdown. We can give footnotes to any word as:

Today's #dgplug session was mentored by mbuf[^1] and kushal[^2]

[^1]:https://github.com/shakthimaan/
[^2]:https://kushaldas.in/

Insertion of <br> tag

When we want to give a line break in HTML, we use a <br> tag. When we give a blank line in between two items, that is not read as line break instead it is taken as a <p> tag. So to give line break using Markdown, we end a line with two or more spaces and then we hit enter.

References:-

1.  https://daringfireball.net/projects/markdown/

As far as I know, these will be enough for a novice to start with Markdown. Though rest depends on your curiosity. Let’s meet in next blog with some new topic. Till then, goodbye.

Be curious and keep learning!