Master Markdown in Ten Minutes
A complete guide to designing content using Markdown
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:
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.
As Markdown gained popularity, a variety of different flavors and specifications of it came into existence.
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:
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.
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!
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
We can also use Setext-style headers for
<h2> by “underlining” the required headers with equal signs (
=) and hyphens (
This is a level 1 header
This is a level 2 header
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:
Designing this in HTML would look something like this:
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!__*
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:
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
- If you add two spaces at the end of a line, you will get a
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.
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] as well. Somewhere in the document, you would define all the names
[Chaitanya Baweja]: https://medium.com/@chaitanyabaweja1
This results in:
A key benefit of using reference links is that multiple links to the same place can be updated at one point.
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:
![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"/>
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.
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
We can create auto-hyperlinks by wrapping the link or even an email address in angled-brackets (
<http://ecosia.org/> is equivalent to
It works for email as well: <email@example.com>
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**.
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
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.
Wrap the phrase in two tilde signs (
~~this phrase is deleted.~~
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
codesnippet, 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 (
>) 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:
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>
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.
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.