When I created my first blog post it had be done through WordPress technology. I knew very little about web development back then but had already created <html> static pages. Creating a dynamic website with database was a game changer. I remember thinking about WordPress in a game changer categories and I even used this technology later on to work with paying clients to deliver what they needed. I still am happy to use WordPress technology but I am more aware of its limitations and it’s heaviness. If the website is a simple collection of few pages without much of an engine needed to support its existence, I will certainly question using WordPress technologies and alike and lean towards simple static solution.

Since I’ve moved to GitHub Pages to host my blog/website, I’ve embarked on a short but very joyful mission to learn how to use Markdown syntax and create simple static pages with clean code. I wanted to share with you most of what I’ve learned to help you understand Markdown and maybe one day you’ll create your own pages with that knowledge.

The limitations

You need to know that Markdown, since it’s very simple by design, has its limitations and it isn’t for people who intend to create complex design. Wheather it’s using advanced typography or moving objects on the page and/or animating them, you’ll want to use a proper <html> page for it and certainly won’t be able to achieve the same effect when using only Markdown syntax. Knowing this, let’s dive into fun.

The main Markdown features I will talk about are:

  1. Text Emphasis
  2. Paragraphs
  3. Headings
  4. Blockquotes
  5. Tables
  6. Create basic lists
  7. Links
  8. Insert images
  9. Insert blocks of code
  10. Boxes

Text Emphasis

In order to bold text you have to use “**” and wrap it around the text like this:

**example text**

If you’d like to italicise, wrap “_” around the text:

_example text_

You can also use both interchangeably. To achieve same effect, I typed:

You can _also use both **interchangeably**_

If you’re wondering how to display * or _ character, you have to use the “escape” character: \ straight before typing special character

If you're wondering how to use \* or \_ character...

Paragraphs

To create these, you simple leave one blank line in text editor. This communicates message to Markdown syntax to start creating next paragraph. If you’d like to create a line break leave two spaces at the end of the line and Markdown compiler with read it and create next part of sentence on new line.

Paragraph 1 with some text here

Paragraph 2 with some more text

A sentence with two blank spaces left after this arrow ->
this cuts next part of sentence onto the next line.

Headings

This one is super simple and easy:

To create this:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

You simply use “x” amount of # signs before the text. But notice there must be space between the # sign and header title. Feel free to add bold or italics in the header text if you’d like.

The code:

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

Blockquotes

You can achieve block quotes by starting line with > and optional space afterwards. To keep the quote together, blank lines inside the quote must contain the >character.

Example:

“If you think you can do a thing or think you can’t do a thing, you’re right.”

- Henry Ford

The code:

> "If you think you can do a thing or think you can't do a thing, you're right."
>
> \- Henry Ford

Tables

Here’s a table:

Number Another number Next number
Five 5 Four
Ten 11 Nine
3 3 8
Two 1 One

The code:

| Number | Another number | Next number |
| :------ |:--- | :--- |
| Five | 5 | Four |
| Ten | 11 | Nine |
| 3 | 3 | 8 |
| Two | 1 | One |

Can you figure out how it works by looking at the code? Try to do it yourself and you’ll learn exponentially faster.

Lists

Use any of *, + or -to make a list. Each list must consistently use the same character.
A space is required after each list character.

Ordered lists start with a number followed by a . or ) and a space.

Examples:

  • Unordered List item 1
  • Unordered List item 2
  • Unordered List item 3
  1. Ordered List item 1
  2. Ordered List item 2
  3. Ordered List item 3

Ordered list can start with any numbers too:

  1. Ordered List item 1
  2. Ordered List item 2
  3. Ordered List item 3

Don’t want a list? Use \ to escape.

12. Escaped “list” item

The code:

* Unordered List item 1
* Unordered List item 2
* Unordered List item 3

1. Ordered List item 1
2. Ordered List item 2
3. Ordered List item 3

Ordered list can start with any numbers too:

5. Ordered List item 1
6. Ordered List item 2
9. Ordered List item 3


Don't want a list? Use `\` to escape.

12\. Escaped "list" item 

Links can be either inline with the text, or placed at the bottom of the text as references. Link text is enclosed by square brackets [], and for inline links, the link URL is enclosed by parentheses ()

How to make text an actual link?
You create a hyperlink by enclosing link inside the angle brackets < link here > https://google.com.
If you don’t use < >, Markdown will not pick up the hyperlink by itself, like now: https://google.com

Inline link:

This is an example of an inline link.

Reference Style link:

A badger is an animal. Badgers are cute.

The Code:

How to make text an actual link?  
You create a hyperlink by enclosing link inside the angle brackets 
`< link here >` <https://google.com>. If you don't use `< >`, Markdown 
will not pick up the hyperlink by itself, like now: https://google.com

Inline link:

This is an [example](http://www.google.com) of an inline link.

Reference Style link:

A [badger][1] is an animal. [Badgers][1] are cute.

[1]:https://bit.ly/2xaXKxx

Inserting Images

Would you like to see an octopus?

Octo

The code:

Would you like to see an octopus?

![Octo](../img/octo.png)

Inside the braces, you can specify http://... or www.sth... links or local path /img/img.png

Blocks of Code

Here’s a piece of code:

var foo = function(x) {
  return(x + 5);
}
foo(3)

And here is the same code with syntax highlighting:

var foo = function(x) {
  return(x + 5);
}
foo(3)

And here is the same code yet again but with line numbers:

1
2
3
4
var foo = function(x) {
  return(x + 5);
}
foo(3)

Boxes

You can add notification, warning and error boxes like this:

Notification

Note: This is a notification box.

Code
{: .box-note}

Warning

Warning: This is a warning box.

Code
{: .box-warning}

Error

Error: This is an error box.

Code
{: .box-error}

Summary

I hope you enjoyed playing with Markdown syntax. I have only discussed some of commands but there’s plenty more, just use your favourite search engine to find them. If you like interactive learning, try this hand’s on tutorial.