In this comprehensive guide, we’ll learn Markdown syntax with examples.

Overview

Markdown is a lightweight markup language that is used to format and style the content of text document. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.

You write markdown in plain text format, which is easier to read and write for most humans, and then Markdown processor convert the plain text into HTML.

There are many markdown processors available. Markdown syntax and support for elements may slightly differ depending upon which markdown processor is being used.

Let’s learn how to format text using various Markdown syntax with examples:-

Block Elements

Headings

Hash # is used to create headings. The number of hashes denotes the heading level for e.g. ### denotes the third level heading.

✅ Always add space between # and the heading for e.g. # Heading 1 works but #Heading 1 doesn’t.
✅ Headings are supported by all Markdown processors.

Alternate syntax for h1 and h2

Alternate syntax is available for first and second level of headings. Add any number of equal signs = and hyphens - below the text for first level and second level heading respectively.

Heading 1
=
            

Heading 1
===========
            

Heading 2
-
            

Heading 2
-----------
            

Paragraphs

Single Paragraph

A simple line of text in Markdown creates a paragraph.

Multiple Paragraphs

A blank line is used to separate paragraphs.

         
I love Markdown.  

It's easier to read and write
as compare to HTML.
            

<p>I love Markdown.</p>
<p>It's easier to read and write
 as compare to HTML.
</p>
            

If a blank line is not used then it is considered as a single paragraph even if the text is in multiple lines.

         
I love Markdown.  
It's easier to read and write
as compare to HTML.
            

<p>I love Markdown. It's easier 
to read and write as compare 
to HTML.
</p>
            

Paragraph with line break

To add a line break in a paragraph, end a line with two or more spaces.

         
I love Markdown.›››
It's easier to read and write
as compare to HTML.
            

<p>I love Markdown.<br> It's
 easier to read and write as 
 compare to HTML.
</p>
            

Note: " › " denotes the space in above example.

❌ Do not indent the paragraph with spaces or tabs. It may render different output by different Markdown processors.
✅ Always keep paragraph left-aligned.
✅ Paragraphs are supported by all Markdown processors.

List

Ordered List

Ordered or Numbered list can be rendered by adding a number followed by period . for e.g. 1. before text.

💡 The numbers don’t have to be in numerical order, but the list should start with the number one i.e. 1.

            
1. First Item
2. Second Item
3. Third Item
            

<ol>
  <li>First Item</li>
  <li>Second Item</li>
  <li>Third Item</li>
</ol>
            

            
1. First Item
1. Second Item
1. Third Item
            

<ol>
  <li>First Item</li>
  <li>Second Item</li>
  <li>Third Item</li>
</ol>
            

            
1. First Item
5. Second Item
2. Third Item
            

<ol>
  <li>First Item</li>
  <li>Second Item</li>
  <li>Third Item</li>
</ol>
            

Nested Ordered List

Nested list items can be created by adding indentation to the line. Each indentation creates a deeper nested level.

            
1. First Item
    1. First Major Item
    2. Second Major Item
        1. First Minor Item
        2. Second Minor Item
2. Second Item
3. Third Item
            

<ol>
  <li>First Item</li>
  <ol>
    <li>First Major Item</li>
    <li>Second Major Item</li>
    <ol>
      <li>First Minor Item</li>
      <li>Second Minor Item</li>
    </ol>
  </ol>
  <li>Second Item</li>
  <li>Third Item</li>
</ol>
            

❌ You can also use parenthesis 1) instead of period 1. but not recommended, because few markdown processor support this.
✅ Ordered lists are supported by all Markdown processors.

Unordered List

Unordered list can be rendered by adding hyphen (or dash) -, asterisk *, or plus + in front of a text.

            
* First Item
* Second Item
* Third Item
            

<ul>
  <li>First Item</li>
  <li>Second Item</li>
  <li>Third Item</li>
</ul>
            

            
- First Item
- Second Item
- Third Item
            

<ul>
  <li>First Item</li>
  <li>Second Item</li>
  <li>Third Item</li>
</ul>
            

            
+ First Item
+ Second Item
+ Third Item
            

<ul>
  <li>First Item</li>
  <li>Second Item</li>
  <li>Third Item</li>
</ul>
            

Nested Unordered List

Nested list items can be created by adding indentation to the line. Each indentation creates deeper nested level.

            
- First Item
    - First Major Item
    - Second Major Item
        - First Minor Item
        - Second Minor Item
- Second Item
- Third Item
            

<ul>
  <li>First Item</li>
  <ul>
    <li>First Major Item</li>
    <li>Second Major Item</li>
    <ul>
      <li>First Minor Item</li>
      <li>Second Minor Item</li>
    </ul>
  </ul>
  <li>Second Item</li>
  <li>Third Item</li>
</ul>
            

❌ Do not mix and match hyphen (or dash) -, asterisk *, or plus + in the same list. Different markdown processors handle it in differently so pick one and stick with it.
✅ Unordered lists are supported by all Markdown processors.

Escape period in ordered and unordered list

If you start an ordered or unordered list item with a number followed by a period for e.g. 1. 1. or - 1. then it is treated as nested ordered list.

            
1. 1. First Item
2. 99. Second Item
            

<ol>
  <li>
    <ol>
      <li>First Item</li>
    </ol>
  </li>
  <li>
    <ol start="2">
      <li>Second Item</li>
    </ol>
  </li>
</ol>
            

            
- 1. First Item
- 99. Second Item
            

<ul>
  <li>
    <ol>
      <li>First Item</li>
    </ol>
  </li>
  <li>
    <ol start="2">
      <li>Second Item</li>
    </ol>
  </li>
</ul>
            

You can get rid of this by adding a backslash \ in front of period for e.g. - 1\.

            
1. 1\. First Item
2. 99\. Second Item
            

<ul>
  <li>1. First Item</li>
  <li>99. Second Item</li>
</ul>
            

            
- 1\. First Item
- 99\. Second Item
            

<ul>
  <li>1. First Item</li>
  <li>99. Second Item</li>
</ul>
            

Escape dash, asterisk and plus in ordered and unordered list

If you start an ordered or unordered list item with dash -, asterisk * or plus + sign then it is treated as nested unordered list. You can escape this by adding a backslash \ in front of them for e.g. \-, \* or \+

            
1. \- First Item
2. \* Second Item
3. \+ Third Item
            

<ul>
  <li>- First Item</li>
  <li>* Second Item</li>
  <li>+ Third Item</li>
</ul>
            

            
- \- First Item
- \* Second Item
- \+ Third Item
            

<ul>
  <li>- First Item</li>
  <li>* Second Item</li>
  <li>+ Third Item</li>
</ul>
            

Definition Lists

Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon : followed by a space and the definition.

            
First Term
: Definition of the first term.


Second Term
: Definition of the second term.
: Another definition of the second term.
            

<dl>
  <dt>First Term</dt>
  <dd>Definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>Definition of the second term.</dd>
  <dd>Another definition of the second term.</dd>
</dl>
            

❌ Definition lists are NOT supported by all Markdown processors.

Blockquotes

Blockquotes with single paragraph

Blockquotes is created by adding greater sign > in front of a text.

Blockquotes with multiple paragraphs

Blockquotes can contain multiple paragraphs. Add a greater sign > on the blank lines as well between the paragraphs.

> This is a blockquote with 
  two paragraphs. I am 
  first paragraph.
>
> I am second paragraph.
          

<blockquote>
  <p>This is a blockquote with 
    two paragraphs. I am
    first paragraph.</p>
  <p>I am second paragraph.</p>
</blockquote>
          

Nested Blockquotes

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional > for each nested level.

> First level of quote.
>
>> This is nested blockquote.
>
> Back to the first level.
          

<blockquote>
  <p>First level of quote.</p>
    <blockquote>
      <p>This is nested blockquote.</p>
    </blockquote>
  <p>Back to the first level.</p>
</blockquote>
          

> First level of quote
>
>> Second level of quote
>>> Third level of quote
>
> Back to the first level
          

<blockquote>
  <p>First level of quote</p>
  <blockquote>
    <p>Second level of quote</p>
    <blockquote>
      <p>Third level of quote</p>
    </blockquote>
  </blockquote>
  <p>Back to the first level</p>
</blockquote>
          

Formatted Blockquotes

Blockquotes can be formatted with other elements such as headers, lists, emphasis and code blocks. Not all the elements works though, try them and see yourself.

> ##### This is a header
> 
> 1. first list item.
> 2. second list item.
> 
> some **example** `code`:
> 
>     return "markdown";
          

<blockquote>
  <h5>This is a header</h5>
  <ol>
    <li>first list item.</li>
    <li>second list item.</li>
  </ol>
  <p>some <b>example</b> <code>code</code>:</p>
  <pre>
        return "markdown";
  </pre>
</blockquote>
          

✅ Blockquotes are supported by all Markdown processors.

Code Blocks

Code blocks are used to write programming code snippet. You can create a code block by indenting every line of the block by at least 4 spaces or 1 tab

function test() {
  console.log("markdown");
}
            

Note: " › " denotes the space in above example.

Fenced Code Blocks

If you find adding 4 spaces or one tab on each line of the block is more inconvenient then some markdown processors also support three backticks ``` or three tildes ~~~ before and after the code block.

function language() {
  console.log("markdown");
}
            

Syntax Highlighting

Many Markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language next to the three backticks for e.g. ```javascript

 ```javascript         
function language() {
  console.log("markdown");
}
```
          

function language() {
  console.log("markdown");
}
  

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```
          

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

```ruby
def index
  puts "hello world"
end
``` 
          

def index
  puts "hello world"
end

```html
<div class="row">
  <div class="col-md-6">
    <h1>Hello World</h1>
  </div>
</div>
``` 
          

<div class="row">
  <div class="col-md-6">
    <h1>Hello World</h1>
  </div>
</div>

Note that syntax highlighting support for a language and how the syntax are displayed for that language varies across different Markdown processors. You can try from this full list of languages, if that works for you:-

abap ('*.abap')
ada ('*.adb', '*.ads', '*.ada')
ahk ('*.ahk', '*.ahkl')
apacheconf ('.htaccess', 'apache.conf', 'apache2.conf')
applescript ('*.applescript')
as ('*.as')
as3 ('*.as')
asy ('*.asy')
bash ('*.sh', '*.ksh', '*.bash', '*.ebuild', '*.eclass')
bat ('*.bat', '*.cmd')
befunge ('*.befunge')
blitzmax ('*.bmx')
boo ('*.boo')
brainfuck ('*.bf', '*.b')
c ('*.c', '*.h')
cfm ('*.cfm', '*.cfml', '*.cfc')
cheetah ('*.tmpl', '*.spt')
cl ('*.cl', '*.lisp', '*.el')
clojure ('*.clj', '*.cljs')
cmake ('*.cmake', 'CMakeLists.txt')
coffeescript ('*.coffee')
console ('*.sh-session')
control ('control')
cpp ('*.cpp', '*.hpp', '*.c++', '*.h++', '*.cc', '*.hh', '*.cxx', '*.hxx', '*.pde')
csharp ('*.cs')
css ('*.css')
cython ('*.pyx', '*.pxd', '*.pxi')
d ('*.d', '*.di')
delphi ('*.pas')
diff ('*.diff', '*.patch')
dpatch ('*.dpatch', '*.darcspatch')
duel ('*.duel', '*.jbst')
dylan ('*.dylan', '*.dyl')
erb ('*.erb')
erl ('*.erl-sh')
erlang ('*.erl', '*.hrl')
evoque ('*.evoque')
factor ('*.factor')
felix ('*.flx', '*.flxh')
fortran ('*.f', '*.f90')
gas ('*.s', '*.S')
genshi ('*.kid')
glsl ('*.vert', '*.frag', '*.geo')
gnuplot ('*.plot', '*.plt')
go ('*.go')
groff ('*.(1234567)', '*.man')
haml ('*.haml')
haskell ('*.hs')
html ('*.html', '*.htm', '*.xhtml', '*.xslt')
hx ('*.hx')
hybris ('*.hy', '*.hyb')
ini ('*.ini', '*.cfg')
io ('*.io')
ioke ('*.ik')
irc ('*.weechatlog')
jade ('*.jade')
java ('*.java')
js ('*.js')
jsp ('*.jsp')
lhs ('*.lhs')
llvm ('*.ll')
logtalk ('*.lgt')
lua ('*.lua', '*.wlua')
make ('*.mak', 'Makefile', 'makefile', 'Makefile.*', 'GNUmakefile')
mako ('*.mao')
maql ('*.maql')
mason ('*.mhtml', '*.mc', '*.mi', 'autohandler', 'dhandler')
markdown ('*.md')
modelica ('*.mo')
modula2 ('*.def', '*.mod')
moocode ('*.moo')
mupad ('*.mu')
mxml ('*.mxml')
myghty ('*.myt', 'autodelegate')
nasm ('*.asm', '*.ASM')
newspeak ('*.ns2')
objdump ('*.objdump')
objectivec ('*.m')
objectivej ('*.j')
ocaml ('*.ml', '*.mli', '*.mll', '*.mly')
ooc ('*.ooc')
perl ('*.pl', '*.pm')
php ('*.php', '*.php(345)')
postscript ('*.ps', '*.eps')
pot ('*.pot', '*.po')
pov ('*.pov', '*.inc')
prolog ('*.prolog', '*.pro', '*.pl')
properties ('*.properties')
protobuf ('*.proto')
py3tb ('*.py3tb')
pytb ('*.pytb')
python ('*.py', '*.pyw', '*.sc', 'SConstruct', 'SConscript', '*.tac')
rb ('*.rb', '*.rbw', 'Rakefile', '*.rake', '*.gemspec', '*.rbx', '*.duby')
rconsole ('*.Rout')
rebol ('*.r', '*.r3')
redcode ('*.cw')
rhtml ('*.rhtml')
rst ('*.rst', '*.rest')
sass ('*.sass')
scala ('*.scala')
scaml ('*.scaml')
scheme ('*.scm')
scss ('*.scss')
smalltalk ('*.st')
smarty ('*.tpl')
sourceslist ('sources.list')
splus ('*.S', '*.R')
sql ('*.sql')
sqlite3 ('*.sqlite3-console')
squidconf ('squid.conf')
ssp ('*.ssp')
tcl ('*.tcl')
tcsh ('*.tcsh', '*.csh')
tex ('*.tex', '*.aux', '*.toc')
text ('*.txt')
v ('*.v', '*.sv')
vala ('*.vala', '*.vapi')
vbnet ('*.vb', '*.bas')
velocity ('*.vm', '*.fhtml')
vim ('*.vim', '.vimrc')
xml ('*.xml', '*.xsl', '*.rss', '*.xslt', '*.xsd', '*.wsdl')
xquery ('*.xqy', '*.xquery')
xslt ('*.xsl', '*.xslt')
yaml ('*.yaml', '*.yml')

✅ Code block (without Syntax highlighting) is supported by all Markdown processors.
❌ Code blocks with Syntax highlighting is NOT supported by all Markdown processors.

Horizontal Rules

You can use three or more asterisks ***, dashes ---, or underscores ___ to create a horizontal rule. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines:-

* * *

***

*****

- - -

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

produce a horizontal rule like below:-

✅ Horizontal rules are supported by all Markdown processors.

Tables

To create a table, use three or more hyphens --- to create each column’s header, and use pipes | to separate each column.

        
 Header 1 | Header 2 
----------|----------
 Cell 11  | Cell 12  
 Cell 21  | Cell 22  
          

<table>
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 11</td>
      <td>Cell 12</td>
    </tr>
    <tr>
      <td>Cell 21</td>
      <td>Cell 22</td>
    </tr>
  </tbody>
</table>
          

You can optionally add pipes on either end of the table.

        
| Header 1 | Header 2 |
|----------|----------|
| Cell 11  | Cell 12  |
| Cell 21  | Cell 22  |
          

Number of hyphens --- doesn’t affect the width of the column. For e.g. both columns will have equal (or auto) width in rendered table even though numbers of - are less in first column.

        
| Header 1 | Header 2 |
| --- |------- |
| Cell 11  | Cell 12  |
| Cell 21  | Cell 22  |
          

Table Column Text Alignment

You can align text in the columns to the left, right, or center by adding a colon : to the left, right, or on both side of the hyphens within the header row.

        
| Index | Stationary Item | Amount
|:--- | :---: | ---: |
| 1.  | Pencil |  10.00 |
| 2.  | Notebook  | 120.00 |
          

Table Cell Text Formatting

You can format the text within table cells. For example, you can add links, code (not code blocks), and emphasis. You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags.

        
| Header 1 | Header 2 |
| -------- |------- |
| **bold** | https://example.com  |
| *italic* | `code` |
          

Escape Pipe in Tables

If you want to use | character as a text in the table then you can escape it with blackslash i.e. \|

        
| Index | Stationary Item |
|:--- | :---: | ---: |
| \|1\|  | Pencil \| Pen |
| \|2\|  | Notebook  |
          

❌ Tables are NOT supported by all Markdown processors.

Task Lists

Task lists allow you to create a list of items with checkboxes. In Markdown applications that support task lists, checkboxes will be displayed next to the content.

To create a task list,
add - [] to create unchecked task list item, and
add - [x] to create checked task list item

        
- [x] Task 1 Completed
- [ ] Task 2 in Progress
- [ ] Task 3 Pending
          

❌ Task lists are NOT supported by all Markdown processors.

Span Elements

Emphasis

Bold

Add two asterisks ** or two underscores __ before and after a word for e.g. **bold** or __bold__ to render as bold.

You can only use asterisks ** and not underscores __ to make part of the word bold. Using __ in part of the word considered as underscore _ and not syntax.

❌ Do not to mix both asterisk and underscore for e.g. *_bold_*, _*bold*_, or _*bold_*. It may render different output by different Markdown processors.
✅ Bold is supported by all Markdown processors.

Italic

Add an asterisk * or underscore _ before and after a word for e.g. *italic* or _italic_ to render as italic.

You can only use asterisk * and not underscores _ to make part of the word italic. Using _ in part of the word considered as underscore _ and not syntax.

✅ Italic is supported by all Markdown processors.

Strikethrough

Add two tilde ~~ before and after a word for e.g. ~~strike~~ to render as strike.

❌ Strikethrough is NOT supported by all Markdown processors.

Bold, Italic and Strike

You can join asterisk *, underscore _ and tilde ~ together for e.g. **_~~bold, italic, and strike~~_** to render bold, italic and strike at the same time.

I am ***~~bold, italic, 
and strike~~***
            

I am <b><i><del>bold, italic, 
and strike</del></i></b>

I am **bold**, *italic*, 
and ~~strike~~
            

I am <b>bold</b>, <i>italic</i>, 
and <del>strike</del>

Escape asterisk, underscore and tilde in emphasis

You can escape the asterisk *, underscore _ and tilde ~ characters to use them in literal way by adding a backslash \ in front of that character.

Link

Inline Link

Inline links is created by wrapping link text in brackets [], followed by URL in parentheses () for e.g. [link text](URL)

<a href="http://example.com/">
example link
</a>

Inline Link with Title

Inline Link can also be created with optional title which is displayed when hover on the link.

[example link](http://example.com/ "Example Title")

<a href="http://example.com/" 
title="Example Title">
example link
</a>

Inline Link with URL and Email Address

URL or email address can quickly be turned into a clickable link by wrapping it in angle brackets <>

<a href="http://example.com">
http://example.com
</a>

<a href="mailto:fake@example.com">
fake@example.com
</a>

Automatic URL and Email Address Link

💡 Many markdown processors (but not all) automatically turns URL and Email Address into clickable link even without wrapping in <>

<a href="http://example.com">
  http://example.com
</a>

<a href="mailto:fake@example.com">
  fake@example.com
</a>

Reference Links

Reference-style links are constructed in two parts: first part is link text which you keep inline and the second part is URL which you define somewhere else in the document.

I get 10 times more traffic 
from [Google][1] than from
[Yahoo][2] or [MSN][3].
 
...
...
...
 
[1]: http://google.com/ "Google"
[2]: http://yahoo.com/  "Yahoo"
[3]: http://msn.com/    "MSN"
          

<p>I get 10 times more traffic
 from 
  <a href="http://google.com/" 
    title="Google">Google</a> 
  than from
  <a href="http://yahoo.com/" 
    title="Yahoo">Yahoo</a> 
  or 
  <a href="http://msn.com/" 
    title="MSN">MSN</a>.
</p>
          

❌ Do not use space in the middle of the URL for e.g. [link](https://www.example.com/my great page), use encoded URL [link](https://www.example.com/my%20great%20page) instead.
✅ Links and email addresses are supported by all Markdown processors.

Image

Inline Image

Image is created by starting with exclamation !, followed by alt text in brackets [], followed by image path or URL in parentheses () for e.g. ![alt-text](image-path)

Markdown	HTML	Output
	<img src="/img/logo.png" alt="Blog">

Inline Image with Title

Image can also be created with optional title which is displayed when hover on the image for e.g. ![alt-text](image-path "Title")

Markdown	HTML	Output
	<img src="./img/logo.png" alt="Blog" title="CodingNConcepts">

Inline Image with Link

Clickable image can also be created with link URL for e.g. [![alt-text](image-path "Title")](URL)

Markdown	HTML	Output
[] (https://codingnconcepts.com)	<a href="https://codingnconcepts.com"> <img src="/img/logo.png" alt="Blog" title="CodingNConcepts"> </a>

Reference Image

Reference-style images are constructed in two parts: first part is alt text which you keep inline and the second part is image patg which you define somewhere else in the document.

Markdown	HTML	Output
![Blog][ref]   ... ... ...   [ref]: /img/logo.png "CodingNConcepts"	<img src="./img/logo.png" alt="Blog" title="CodingNConcepts">

✅ Images are supported by all Markdown processors.

Code

Enclose the text in backticks ` to display that as a code for e.g `code`.

Escape backticks in code

You can escape the backtick ` character to use it in literal way by enclosing the code text in double backticks ``.

Note the space between double backticks `` and `nano`, otherwise it won’t work.

Escaping Characters

Sometime we want to display the characters in literal way which are used as a Markdown syntax. In such cases, add a backslash \ in front of the character.

You can escape the following characters in Markdown:-

Summary

Congratulations! We have learned all the syntax supported by most of the Markdown processors.

You can further read following useful resources:-

• John Gruber’s Markdown documentation written by the creator of Markdown.
• Markdown Guide for getting-started with Markdown
• Markdown Tutorial to try Markdown syntax in the web browser.
• Awesome Markdown is a list of Markdown tools and learning resources.