Master Markdown in Ten Minutes
By: Chaitanya Baweja
Tags: Programming, Design, Software Development, Markdown, Web Development

Basic Syntax

As Markdown gained popularity, a variety of different flavors and specifications of it came into existence.

Examples include Common Mark, GitHub Flavored Markdown and Markdown Extra. But the basic elements that were outlined in John Gruber’s original design document are supported by all applications.

Markdown was designed with utmost focus on readability. Consequently, you will find its syntax to be simple and intuitive.

Here are the elements you’ll use most often:

Paragraphs

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. If two lines need to be converted into paragraphs, you must leave an empty space between them. Take a look:

This is paragraph 1.

No empty line in between, so I am still on paragraph 1. This seems like paragraph 2. Shouldn't this be paragraph 3 then.

Output: Define paragraphs by simply leaving a blank line

Note: Multiple blank lines will be rendered as a single blank line or a single <p> tag. If you need to add multiple blank lines, see this question on Stack Overflow.

But what if we need soft line breaks rather than a new paragraph. Imagine writing the following poetry:

Rather than blank lines, we need single line breaks <br> . This can be done by inserting two spaces after each new line.

As you might find it difficult to see blank spaces, each (space) in the snippet below represents a space on the keyboard.

I eat my peas with honey. (space)(space)

I've done it all my life. (space)(space)

It makes the peas taste funny. (space)(space)

But it keeps them on the knife!

Headers

In Markdown, a heading is created by prefixing a line with the # symbol. The number of hashes indicates the level of the heading.

One hash is converted to an H1 (HTML heading tags), two hashes to an H2 and so on. There are a total of six levels that you can make use of, but for most writing, you’ll rarely need more than three.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Output: Headings are created by prefixing the # symbol

We can also use Setext-style headers for <h1> and <h2> by “underlining” the required headers with equal signs ( = ) and hyphens ( - ), respectively.

This is a level 1 header

=============



This is a level 2 header

-------------

Output: Setext style headers

Block-quotes

There are times when you need to draw extra attention to a quote from a different source or highlight an important point. Such dire times call for Markdown’s block-quote syntax. Block-quotes are indicated using email-style > angle brackets.

I have designed a somewhat complex example to help you appreciate the core idea behind Markdown: Readability.

Suppose you wish to see the following output:

Output: Block-quotes are extremely useful

Designing this in HTML would look something like this:

Writing the same blockquote in HTML

Let’s take a look at how the same can be done using Markdown.

> This is a blockquote.

> Every line should have a `>` bracket in front.

>

> You can also create paragraphs in blockquote.

>

> ## This is a heading inside a blockquote

> Who said you only get one level

>> of indentation?

>

> Like this already?

I hope I have made my point clear.

Phrase emphasis: italics and bold

Text can be easily styled as italics or bold using Markdown.

To make a phrase italics in Markdown, surround it with an underscore ( _ ) or an asterisk ( * ). For example, _hello_ would become hello.

Similarly to make a phrase bold in Markdown, surround it with two underscores ( __ ) or two asterisks ( ** ). For example, __hello__ would become hello.

You can also use both of them together by using triple asterisks( *** ) or triple underscores( ___ ). Let’s take a look:

*I am italics.*

_And so am I._ **I am bold.**

__And so am I.__ ***I swing both ways.***

**_As do I!_**

*__And me also!__*

___ME TOO!___

Output: Use italics for little and bold for strong emphasis

Lists

Two types of lists are supported in the original Markdown: ordered (lists with numbers) and unordered (lists with bullet points).

To create an unordered list, preface each item in the list with an asterisk ( * ). You can also use pluses ( + ) and hyphens ( - ) instead. Each list item also gets its own line.

For example, a to-do list in Markdown might look like this:

**To Do List**

* Write a Markdown Tutorial

* Add jokes in it

* Apologize for the stupid puns

* Do laundry

This will result in:

An ordered (numbered) list, on the other hand, is prefaced with numbers, followed by periods, rather than asterisks:

1. Apple

2. Orange

3. Banana

Output:

Note: You can actually put the numbers in any order. You could start with 2, instead of 1. No matter what you do, the output will remain the same.

We can also add more depth to our lists and create sub-lists. For adding a new level, simply indent or add an extra space before each asterisk. Take a look:

* Item One

* Item Two

* Sub-Item One

* Sub-Item Two

* Sub-Sub-Item One

* Sub-Item Three

* Item Three

This results in:

You can write multi-paragraph list items using the same syntax.

If you put blank lines between items, you’ll get <p> tags.

tags. If you add two spaces at the end of a line, you will get a <br> tag.

1. A list item with a line break.

This is the same paragraph. This is a new paragraph in the same item.

2. Second item in the list.

Output:

Links

There are two different types of links in Markdown, inline and reference. Both of them result in the exact same output.

To create an inline link, use square brackets ( [ ] ) to wrap the link text, and then wrap the link in parenthesis ( ( ) ). For example, to create a hyperlink to this search engine, you write:

For further research, [use](www.ecosia.org)

Note: You can also add an HTML title attribute as follows: For further research, [use](www.ecosia.org "hover title")

Reference links are actually a reference to another place in the document. You refer to your links using names that are defined elsewhere in the document. Take a look:

* Here is a [reference link][Chaitanya Baweja] to my profile.

* References are case-insensitive. So, this would work as well. [reference link][chaitanya baweja] .

* Can be done with [numbers][1] as well.

[Chaitanya Baweja]:

[1]: Somewhere in the document, you would define all the names[Chaitanya Baweja]: https://medium.com/@chaitanyabaweja1 [1]: https://www.numberphile.com/

This results in:

A key benefit of using reference links is that multiple links to the same place can be updated at one point.

Images

The syntax for adding images is very similar to the link syntax. The only difference is that you need to preface images with an exclamation point ( ! ).

The below example demonstrates both inline and reference style images:

Inline Image

![alt text](/path/to/img.png) Reference style image

![alt text][image path] [image path]: /path/to/img.png

Both of the above examples produce the same HTML code: