LearnExplaining Markdown

Matt West
writes on April 8, 2013

Share with your friends


Markdown is a simple text-based markup language and conversion tool that allows writers to create great content for the web without having to worry too much about HTML. The syntax of the language is designed to be easy to learn and intuitive. It’s ideal for people that write content for the web but that might be distracted by the HTML syntax.

Note: Markdown wasn’t really designed as a language for creating complete web pages. It’s more suitable for just content areas like the body of a blog post, an article or web page copy.

Markdown files use the .md or .text extensions.

A common problem that faces HTML is that having all those tags in your markup makes it hard to actually read the content without viewing the page in a web browser. Markdown aims to solve this problem by providing a simple, unobtrusive syntax for marking up content elements such as headings, links, lists, images and more!

The Markdown syntax consists of a number of standard characters that represent HTML elements. When you are ready to publish your content, you pass your Markdown code through a converter that generates the HTML code for you.

Converting Markdown to HTML

There are a number of different ways that you can convert your Markdown to HTML.

Use a plugin for your Content Management System.

There are plugins available for many popular Content Management Systems that will allow you to write your content using Markdown. Your Markdown will then be converted to HTML when you save your changes. If you are a WordPress user check out WP-Markdown.

Use a plugin for your Text Editor.

There also plugins available for popular text editors that provide tools for previewing and converting your markdown code. Federico Viticci put together a great list of plugins for Sublime Text 2.

Finally, you can also your the Command Line Tools.

The command line tools that can be downloaded from the project website also allow you to convert your markdown to HTML. If you’re a Mac user with homebrew you can simply do brew install markdown at the terminal to get these tools installed.Once installed, to use the command line interface you issue the following command.

markdown /path/to/input_file.md > output.html

Before I take you through the Markdown syntax lets take a look a simple example.

# Team Treehouse
Our mission is to bring affordable Technology education to people everywhere, in order to help them achieve their dreams and change the world.

Running this through the Markdown converter would produce the following HTML.

<h1 id="team-treehouse">Team Treehouse</h1>
<p>Our mission is to bring affordable Technology education to people everywhere, in order to help them achieve their dreams and change the world.</p>

As you can see, the Markdown version is much easier to read. This is one of the biggest benefits of using Markdown and is also one of the reasons that a lot of experienced developers opt to use it over writing pure HTML.

Now that you understand the problem that Markdown is out to solve lets take a detailed look at the syntax.


There are two different styles for marking up headings, setext and atx. In this article I’m going to focus on the atx style as it supports more heading levels (six levels against the two levels support by the setext style).

To create headings in Markdown you simply prefix the heading text with a pound sign (#) followed by a space. The number of pound signs that you use indicates the importance of the heading.

# Level 1 Heading  
## Level 2 Heading  
### Level 3 Heading  
#### Level 4 Heading  
##### Level 5 Heading  
###### Level 6 Heading

This Markdown would produce the HTML below.

<h1>Level 1 Heading</h1>
<h2>Level 2 Heading</h2>
<h3>Level 3 Heading</h3>
<h4>Level 4 Heading</h4>
<h5>Level 5 Heading</h5>
<h6>Level 6 Heading</h6>

In accordance with the HTML specification you can only use up to six pound signs (indicating a level 6 heading). If you use more than six pound signs the converter will not create a heading at all and the pound signs will be visible to the reader.


Creating paragraphs of text is easy. Simply separate paragraphs using one or more blank lines, you don’t need to use any special characters.

This is a paragraph of text.

This is another paragraph.

This Markdown would create two paragraphs.

<p>This is a paragraph of text.</p>
<p>This is another paragraph.</p>

Line Breaks

If you want to add a line break simply add two spaces to the end of the line.

This is the first line.  
This is the second line.

The first line in this example has two spaces at the end so the HTML will include a line break. A single paragraph element encloses both of the lines of text.

<p>This is the first line. <br />
This is the second line.</p>


To create a blockquote you need need to prefix each line of the blockqoute with an angled bracket (>) followed by a space. You can create multiple paragraphs within a blockquote using empty lines, as you did before.

> A person who never made a mistake never tried anything new.

> The true sign of intelligence is not knowledge but imagination.

This Markdown would become the following HTML.

    <p>A person who never made a mistake never tried anything new.</p>
    <p>The true sign of intelligence is not knowledge but imagination.</p>

(Quotes provided by the mind of the great Albert Einstein.)

Phrase Emphasis

Adding emphasis to phrases is pretty straightforward. To create a <strong> element, wrap the phrase within double asterisks (**) or double underscores (__). Creating an <em> element requires single asterisks or underscores.

**Double asterisks produces a strong element**    
__As does double underscores__

*A single asterisk produces an em element*  
_As does a single underscore_

Here’s the HTML conversion (I added some line breaks).

<p><strong>Double asterisks produces a strong element</strong> <br>
<strong>As does double underscores</strong></p>

<p><em>A single asterisk produces an em element</em> <br>
<em>As does a single underscore</em></p>


Markdown supports both ordered and unordered lists as well as nesting.

Unordered Lists

Unlike in HTML you don’t need to worry about creating an enclosing element for Markdown lists, you only need to focus on the actual list items. To create an unordered list you need to prefix each list item with either an asterisk (*), minus (-) or plus (+) and the follow that up with a space. It is up to you which symbol you use, just be consistent once you have made your choice.

* Item One
* Item Two
* Item Three

- Item One
- Item Two
- Item Three

+ Item One
+ Item Two
+ Item Three

The Markdown above shows three examples of unordered lists using varying syntax. All of these examples will produce the same HTML shown below.

<li>Item One</li>
<li>Item Two</li>
<li>Item Three</li>

Ordered Lists

To create an ordered list you prefix each list item with a number, followed by a period, and finally a space. It’s worth noting that the actual number you use doesn’t matter. This is because the number that is displayed to the reader is handled by the browser and not in HTML (although you can manipulate the display behavior using CSS).

1. Item One
2. Item Two
3. Item Three

1. Item One
1. Item Two
1. Item Three

Both the of the Markdown examples above will be converted into the following HTML.

<li>Item One</li>
<li>Item Two</li>
<li>Item Three</li>

Nested Lists

To create nested lists you need to indent the nested list items using 4 spaces (or one tab). You can mix-and-match list types when nesting. So you could have an ordered list nested within an unordered one and vice-versa.

* Item 1
    * Item 1.1
    * Item 1.2
* Item 2
* Item 3

The example above demonstrates nesting an unordered list within another unordered list. This would produce the following HTML.

    <li>Item 1
        <li>Item 1.1</li>
        <li>Item 1.2</li>
    <li>Item 2</li>
    <li>Item 3</li>

The syntax for creating links has been simplified as much as possible. To create a link you first place the link text within square brackets. Immediately following the closing square bracket you then add a pair of regular brackets that contain the link.

[Team Treehouse](http://teamtreehouse.com)

The Markdown above will create a simple link to the Treehouse home page.

<a href="http://teamtreehouse.com">Team Treehouse</a>

You can also add a title attribute to your link by adding the title text after the URL but within the brackets (as shown below). Make sure that you add a space between the URL and the title text.

[Team Treehouse](http://teamtreehouse.com "Learn Web Design, Web Development and More!")

This example would produce the following HTML link, complete with title attribute.

<a href="http://teamtreehouse.com" title="Learn Web Design, Web Development and More!">Team Treehouse</a>


Images use a similar syntax to links. This time the text you place within the square brackets will form the alt text for the image and the URL in the regular brackets will be used as the path to the image file. The whole syntax is prefixed with a bang (!) which indicates that an image should be created not a link.

![The image alt text goes here](http://example.com/icon.png)

The example above will be converted to the following HTML.

<img src="http://example.com/icon.png" alt="The image alt text goes here">


It’s quite common for us programmers to write blog posts that contain code that needs to be displayed in plain text. HTML provides the <pre> and <code> elements to help us accomplish this.

Markdown supports both inline code snippets and code blocks.

Inline Code Snippets

In HTML we would use the <code> element to markup occurrences of variable or file names when they appear inline. When using Markdown we just need to wrap the inline code snippet in backticks (`).

The `index.html` file contains the homepage for your website.

The example above uses backticks to indicate that index.html should be wrapped in a <code> element.

<p>The <code>index.html</code> file contains the homepage for your website.</p>

Code Blocks

For occasions when you have a larger body of code to markup you need a slightly different approach. In HTML we would use <pre> and <code> elements to markup a body of code and preserve the layout of the text.

With Markdown you just need to indent the whole code block by 4 spaces (or one tab). Just like you do with nested lists.

    function solveForX(y) {
        return solve(y);

The code in the example above has been indented by 4 spaces, indicating that it should be wrapped in <pre> and <code> elements.

<pre><code>function solveForX(y) {
    return solve(y);

Notice that the indents within the original block of code are unaffected in the HTML output.

Horizontal Rules

To add horizontal rules in your markdown simply use three or more asterisks, minus signs, or underscores in a row. These must be on a single line with no other content for the converter to create a horizontal rule.


All three of the examples above will produce a <hr> element.

Inline HTML

Markdown is really useful for taking care of simple markup but it falls down when it comes to more complex structures like tables. Luckily you can mix HTML and Markdown together. The Markdown converter will preserve any HTML that it encounters within your Markdown files.

This is a standard paragraph of **text**.

            <th>First Name</th>
            <th>Last Name</th>

Here is some more text that the _Markdown_ converter will put into a new paragraph.

In the example above the Markdown converter will leave the <table> untouched but will create HTML elements for the remaining content.

<p>This is a standard paragraph of <strong>text</strong>.</p>
            <th>First Name</th>
            <th>Last Name</th>
<p>Here is some more text that the <em>Markdown</em> converter will put into a new paragraph.</p>

It is worth mentioning that the converter does not process Markdown syntax within block-level HTML elements (<div>, <p>, etc.) that have been manually coded. For example the converter would not create a <strong> element around the word ‘Hello’ in this example.

<div>**Hello** Treehouse!</div>

Escaping Markdown Syntax

You may run into instances when the converter is interpreting your use of the syntax characters as a signal to create HTML elements when you don’t really want it too. This can be frustrating at first, but don’t fear there is a solution!

If you want the converter to ignore a character you simply prefix it with a backslash (\).

For example, the asterisks in the example below are escaped with a backslash so the converter would not create an unordered list.

\* Item One  
\* Item Two  
\* Item Three

I’ve listed all of the characters used in Markdown syntax below for your reference.

\ ` * _ { } [ ] ( ) # + - . !


Markdown is a fantastic language for quickly putting together a blog post or some content for a website. Personally I use it a lot. In fact, I used it to write this article.

The main drawback of Markdown is that you are confined to a fairly limited subset of what is available in HTML. Most notably, you cannot define the majority of element attributes in Markdown alone. That said, Markdown wasn’t designed to be a replacement for HTML. It aims to make it simpler for web writers to create content. A goal that I think it achieves very well. The ability to mix-in HTML also allows you to circumvent the issue of being occasionally limited by the native Markdown syntax.

If you haven’t tried using Markdown before I encourage you to check it out. If you regularly write content for the web you could find that it makes your writing experience much more enjoyable.

10 Responses to “Explaining Markdown”

  1. Wow Matt, this was an amazing Article! Thank you very much for showing us Markdown. I had no idea how much simpler writing for the web could have been. I have personally always used HTML when writing an article, but Markdown fixes that problem. I would definitely love to see this subject built in, maybe some examples, etc. Do you know of a good compiler for Windows? Thank you so much again! 😀

  2. Great deep dive Matt!

  3. エルメス スーパーコピー品激安通販!完璧品質!お客様の満足度は業界No.1です!
    [url=http://www.okakaku.com/brand-8-copy-0-cheap-0-max0-attr0-3-sort_order%20Desc%2cgoods_id-DESC.html]人気スーパーコピーブランド時計激安通販専門店私達は長年の実体商店の販売経験を持って、先進とプロの技術を持って、高品質のスーパーコピー時計づくりに 取り組んでいます。最高品質のロレックス時計コピー、カルティエ時計コピー、IWC時計コピー、ブライトリング時計コピー、パネライ時計コピー激安販売中商品の数量は多い、品質はよい。海外直営店直接買い付け!★ 2015年注文割引開催中,全部の商品割引10% ★ 在庫情報随時更新! ★ 実物写真、付属品を完備する。 ★ 100%を厳守する。 ★ 送料は無料です(日本全国)!★ お客さんたちも大好評です★ 経営方針: 品質を重視、納期も厳守、信用第一!税関の没収する商品は再度無料にして発送します[/url]

  4. 100%実物写真ですし、品質が完璧です!”スーパーコピーブランド財布激安 偽物財布激安コピー ルイヴィトン財布偽物,偽物財布コピーエルバーキンコピースーパーコピー財布ブランド財布コピーブランドコピー激安バレンシアガ スーパーコピー激安ロレックス スーパーコピー時計ブランド財布激安 偽物財布激安コピー ルイヴィトン財布偽物,偽物財布コピーブランド激安市場-jck35販売:ブランド財布コピー,激安ブランド,財布コピー,偽ブランド,偽 ブランド財布,偽物ブランド財布,ブランドコピー,ヴィトンコピー,ルイヴィトン財布偽物, シャネル財布コピー,グッチ財布コピー,エルメス財布偽物,D&G 財布コピー,ボッテガ 財布 .2013年新作スーパーコピーロレックス,スーパーコピーロレックス時計通販スーパー コピー品その他の世界一流ロレックススーパーコピー時計品を扱っています。 ホームページをクリックして商品をご覧下さい.ロレックスコピー,業界No.1人気スーパーコピーロレックス腕時計専門販売ロレックスコピー(ROLEXスーパーコピー)のロレックス レプリカ販売専門店です。すべての商品は品質2年無料保証です,ロレックス デイトジャスト 偽物,人気満点ロレックス コピーn級品新作大特集
    [url=http://www.newkakaku.com/chz1.htm]スーパーコピーブランド 代引き安心老舗当店は海外高品質のブランドコピー 代引き,スーパーコピー 代引き通販人気老舗です。2015新作 ルイヴィトン コピー代引き、シャネル コピー代引き、[/url]

  5. 日本ロレックス時計コピー品ロレックスレプリカ、日本ロレックス時計のロレックスコピー品ロレックス時計,ロレックスレプリカ,ロレックスコピー,日本ロレックス,ROLEX,ロレックスオーバーホール,ロレックスレプリカ ,ロレックス修理,ロレックスミルガウス,ロレックス中古,ロレックスサブマリーナ,ロレックスデイトナ,ロレックス中古,ロレックスアンティーク,ロレックス買取”弊社はROLEXの商品特に大人気のロレックスデイトナシリーズのロレックス時計の種類を豊富に取り揃えます。日本ロレックス時計とロレックスレプリカのロレックスコピー品の品質よくて、激安税込み価格でご提供します。
    スーパーコピー腕時計,ロレックスコピー,ブライトリングコピー,ボーム&メルシエコピー時計コピー業界最高峰スーパーコピー時計通販専門!7年以上の販売実績を 持つ時計コピー老舗!時計コピーであれば何でも揃えられます コピー時計 時計スーパーコピー通販専門店!時計コピー時計販売通販! コピー時計スーパー コピー等の 最高級のレプリカコピー時計を販売ロレックスコピー,ガガミラノコピー ,IWCコピー ,オメガコピー ,フェラーリコピー ,フランクミュラーコピー ,ベル&ロスコピー ,各種のブランドはコピーを表しますコピーを表して、時計をコピーして、スーパーコピーは代 金引換払いにして、スーパーはブランドをコピーして、スー パーは時計をコピーして代金引換払いにして、スーパーは時 計をコピーして、スーパーは腕時計をコピーして、ブランド はスーパーマーケットを表してコピーして、ブランドのスー パーマーケットはコピーして、ブランドはコピーを表して、 腕時計はコピーします ,ボーム&メルシエコピー時計コピー業界最高峰スーパーコピー時計通販専門!7年以上の販売実績を 持つ時計コピー老舗!時計コピーであれば何でも揃えられます コピー時計 時計スーパーコピー通販専門店!時計コピー時計販売通販! コピー時計スーパー コピー等の 最高級のレプリカコピー時計を販売ロレックスコピー,ガガミラノコピー ,IWCコピー ,オメガコピー ,フェラーリコピー ,フランクミュラーコピー ,ベル&ロスコピー ,各種のブランドはコピーを表しますコピーを表して、時計をコピーして、スーパーコピーは代 金引換払いにして、スーパーはブランドをコピーして、スー パーは時計をコピーして代金引換払いにして、スーパーは時 計をコピーして、スーパーは腕時計をコピーして、ブランド はスーパーマーケットを表してコピーして、ブランドのスー パーマーケットはコピーして、ブランドはコピーを表して、 腕時計はコピーします http://www.bagkakaku.com/vuitton_belt.html

  6. 2015年の新素材-新作!高品質 腕時計高品質の追求 超N品を良心価格で提供詳しくは以下のようなブランドがあります。HERMES(バッグ、財布、時計) CHANEL(バッグ、財布、時計)LOUIS VUITTON(バッグ、小物、財布、時計) BVLGARI(財布、時計)Christian Dior(バッグ、財布) COACH(バッグ、財布)GUCCI(バッグ、財布) ROLEX(時計)OMEGA(時計) IWC(時計)FRANCK MULLER(時計) HUBLOT(時計)クロエ CHLOE バッグなどです。ご不明点が ございましたらお気軽にお問い合わせください
    激安 ブランドスーパーコピー新しいものを販売しています。ルイルイヴィトンコピー、グッチコピー、シャネルコピー、ブランドコピー、ブランドスコピー、ブランドコピー時計などルイヴィトンコピー 激安 ブランド、スーパーコピー、代引き対応、レプリカ、安心通販ルイヴィトン偽物、シャネル偽物、グッチ偽物、エルメス偽物、クロエ偽物、カルティエコピー、オメガコピー、IWCコピー楽天ヴィトンコピー屋 http://www.brandiwc.com/brand-5-copy-0.html

Leave a Reply

Want to learn more about HTML?

HTML is what the Internet is built on. Learn how to build your first website from scratch.

Learn more