Master Markdown in Ten Minutes

A complete guide to designing content using Markdown

Chaitanya Baweja
Feb 27 · 9 min read
Photo by Greg Rakozy on Unsplash

In 2004, famous Apple commentator and online blogger, John Gruber, was tired of writing long, laborious HTML tags to properly format his content. This frustration led to the creation of a plain text formatting writing syntax for web writers: Markdown.

Markdown is a plain text-to-HTML conversion tool for content creators. It allows you to quickly design easy-to-read, easy-to-write content for the web, and have it magically converted to clean, structured HTML.

Let’s take a quick example of Markdown in action:

I’m not *crazy*. My **mother** had me [tested](https://www.youtube.com/watch?v=mr6XHJ7qcSE).

This will become:

Quote from The Big Bang Theory

With just a couple of extra characters, Markdown makes rich document formatting quick and beautiful.

Imagine writing the same line in HTML:

I’m not <em>crazy</em>. My <strong>mother</strong> had me <a href="https://www.youtube.com/watch?v=mr6XHJ7qcSE">tested</a>.</p>

HTML tags add lots of in-line noise. They make a document hard to read. For people unfamiliar with HTML, it could be impossible.

Formatting text in Markdown has a very gentle learning curve. This article is designed to acquaint you with the syntax in less than ten minutes.


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:

Source: link

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:

Designing the same in HTML
Designing the same in HTML
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.
  • 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.
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:

<img src="/path/to/img.png" alt="alt text"/>

Advanced Syntax

I hope that by this point you are comfortable with the basics of Markdown. Markdown has many “extended” implementations that have a lot more to offer.

These include tables, task lists, code-highlighting, etc. These added capabilities are not supported by all implementations but are widely used and hence, worth looking at.

Horizontal rule

You can easily add horizontal rules (<hr/>) using three or more asterisks or hyphens, with or without spaces.

#### Section 1
---
#### Section 2
***
#### Section 3
- - -
#### Section 4
*********
Output: Notice the horizontal lines between sections

Auto-links

We can create auto-hyperlinks by wrapping the link or even an email address in angled-brackets (<>).

<http://ecosia.org/> is equivalent to
[http://ecosia.org/](http://ecosia.org/).
It works for email as well: <john.doe@rediffmail.com>
Output: auto-links work for email addresses as well

Escaping characters

Let’s say you wish to type **bold**, without it becoming bold. Using the backslash(\) before the asterisk (* ) will prevent any *accidental* conversion to HTML.

I want to say \*\*bold\*\* without being **bold**.
Use backslash for escaping characters

Task lists

The syntax is very similar to a normal unordered list. You simply need to add a symbol before every item denoting completion or not. Completion is denoted by [x] and non-completion by [] .

**To Do List**
- [x] Write a Markdown Tutorial
- [x] Add jokes in it
- [x] Apologize for the stupid puns
- [ ] Do laundry

Tables

In GitHub-Flavored Markdown, you can create tables using pipes | and hyphens -. We use hyphens to create each column’s header, and then use pipes to separate each column.

| First Column | Second Column | Third Column |
| :----------- | :-----------: | -----------: |
| Left-align | Center-align | Right-align |
| Item 1 | Item 2 | Item 3 |

Note: You must include a blank line before your table for it to correctly render.

You can find more details about tables in Markdown on GitHub.

I am personally not a big fan of tables in Markdown. They can be quite cumbersome and then there are other issues like this issue on Stack Overflow.

Strike-through

Wrap the phrase in two tilde signs (~~ ).

~~this phrase is deleted.~~

Code

If you’re writing a programming blog, you will definitely use code snippets to guide your readers through a particular syntax.

  • For a simple quick code snippet, use a single back-tick around the snippet.
  • For specifying multiple lines of code, indenting by four spaces or a tab turns an entire paragraph into a code block.
We can show a simple `<html>` code snippet by surrounding the `code snippet` in back-ticks.If we need an entire code block, indent the block with 4 spaces.    This is first line of code
This is second line of code

This results in:

Note: Any ampersands (&) and angle brackets (< or >) are automatically translated into HTML entities.

Now, for most languages you might want some additional features like syntax highlighting. This is available in various extensions of Markdown like GitHub- flavored Markdown.

We surround the code by three ticks (```) and we specify the programming language used. In the example below, we use Python.

To check which elements of a list are even, do the following:    ```python
for number_i in given_list:
if number_i%2 ==0:
print(number_i," is even")
```

This will result in:

Embedding HTML

And finally, if you need extra functionality, you can always use plain old HTML within a Markdown document. Markdown supports all regular HTML elements. For example:

This part in **Markdown**.  
<p>This part in <strong>HTML</strong>.</p>

Conclusion

Quoting John Gruber:

“The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.

The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Markdown has become a de-facto writing standard for academics, scientists, writers, and many more. Documents written in Markdown can be easily shared across a variety of platforms.

GitHub and Reddit are using Markdown to style their comments. Many popular editors like Atom provide built-in support for Markdown.

Feel free to use HTML for advanced formatting. As Markdown supports all regular HTML tags, you can really do anything with it.

I would highly recommend you reinforce these ideas by writing your first Markdown document and getting a feel for the basics.


Better Programming

Advice for programmers.

Thanks to Zack Shapiro

Chaitanya Baweja

Written by

Machine Learning Engineer | Python | Data Analytics | Economics | Physics

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade