Markdown is a lightweight syntax of markup for plain text documents. It allows us to add semantics and style to our documents without overpowering them with code and angle brackets.

Markdown can easily be converted to HTML and its tags match those found in HTML—there is a one-to-one mapping.


Markdown files are simply plain text files. But often the extension of the file is changed to .md to signify Markdown syntax.


One of the most common uses for Markdown files is Readmes. You’ll notice that GitHub will render your Markdowned Readme file and present it in a styled view. Just name your Readme and GitHub will do the rest.

GitHub actually uses Markdown in lots of places including: issues and wikis.

Another really common use is content preparation for responsive websites. It’s a really good way to organize and understand the structure of content without forcing HTML upon your authors.


For paragraphs in Markdown there is no visible syntax, just write lines of text and separate them by a blank line. Markdown will automatically convert text with blank lines between into paragraphs.


This is the first paragraph.

This is the second paragraph of text.

Bold & italic

To make something italic, surround it in a single set of asterisks. To make something bold, surround it in double asterisks.

Some words are *italic* and some words are **bold**.


Headings are denoted using a hash symbol in front:

# Heading level 1
## Heading level 2
### Heading level 3


Lists are created by putting dashes in front of lines of text:

- List item 1
- List item 2
- List item 3

If you want to make an ordered list, instead use numbers:

1. Item A
2. Item B
3. Item C

To add links there is a little more syntax:

[Link this text](


To add images, use a syntax similar to links:

![Image alt attribute](

Horizontal rules

To add horizontal rules, use three dashes:

This is a paragraph.


This is another paragraph, separated by a horizontal rule.


Inside Markdown, code samples can be written two ways:

Inline — written inside other text with a single backtick:

The `<h1>` tag denotes the most important text on the page.

Code blocks — starting with 3 backticks and ending with 3 more backticks:


With code blocks you can even specify the syntax by writing it directly after the 3 starting backticks:


Task lists

And finally, GitHub supports task lists in Markdown files using the following format:

- [ ] Thing to do
- [ ] Another thing to do
- [x] Thing that’s already done

GitHub will even convert those to checkboxes in specific locations.

Video list

  1. Markdown: applications
  2. Markdown: syntax basics
  3. Markdown: inserting links
  4. Markdown: inserting images
  5. Markdown: inserting code samples
  6. Markdown: task lists

Markdown apps