The Complete Guide To Markdown

Have you ever wondered how these "readme.md" files are written on Github? Or how Blog posts like this are written? Whether you're new or you have been a programmer for a while then you probably have heard of "Markdown" but you probably never had the chance to learn it or you probably know some of it's syntax but can't quiet get the grasp of it. No problem! This is tutorial is for anyone who wants to learn Markdown and add a new skill to their belt because it's something everyone should know.

So what's Markdown Exactly❓

Markdown is a lightweight markup language that you can use to add formatting plaintext text documents. Created by John Gruber in 2004 for purpose of readability and ease of use. It can be converted to HTML and other formats. It's file extension usually ends in ".md".

Depending on the application you use, you may not be able to preview the formatted document in real time. But that’s okay. Markdown syntax is designed to be readable and easy to be used by everyone, so the text in Markdown files can be read even if it isn’t rendered by your application.

What's Markdown used for?🤔

Markdown can be used for everything. People use it to create websites, documents, presentations, email messages, static site generators (Gatsby, etc), forums, and technical documentation. Websites like Reddit and GitHub support Markdown, and lots of desktop and web-based applications support it.

Type of formats that Markdown support:

• Headings
• Emphasis
• Links
• Lists
• Code Blocks
• Images
• Blockquotes
• Horizontal rules

Setup💻

Now I suggest coding along with this Blog if you want the full benefit.

Online Editors

• Dillinger
• StackEdit
• Editor.md

Downloadable Editors

• VSCode
• Typora
• MarkdownPad

Note❗: If you are using a text editor like VSCode I suggest getting a Markdown previewer extension to be able to render your Markdown right in the text editor.

Headings

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level (Like h1, h2, h3, etc. in HTML).

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

Best Practices 👏

Dont't do this ❌	Do this ✔️
#Heading	# Heading

Paragraphs

Paragraphs do not require any tags or signs. They are fairly simple.

Markdown	Rendered
This is a paragraph	This is a paragraph
You can just type anything	You can just type anything

Best Practices 👏

Dont't do this ❌	Do this ✔️
Don't add tabs or spaces in front of paragraphs.	Don't add tabs or spaces in front of paragraphs.

Emphasis

To make text either bold or italic

• Bold by putting ** or __ before and after your text
• Italic by putting * or _ before and after your text

Bold

Markdown	Rendered
This is **bold text**	This is bold text
Another __bold text__	Another bold text

Italic

Markdown	Rendered
This is *Italic text*	This is Italic text
Another _Italic text_	Another Italic text

Bold and Italic

Markdown	Rendered
This is _*This is bold and italic at the same time*_	This is bold and italic at the same time
This is also *_This is bold and italic at the same time_*	This is also bold and italic at the same time

Horizontal Rule

Add three or more asterisks ***, dashes ---, or underscores ___ on a line by themselves.

***
---
___ 

Note❗: Add a blank line before and after the horizontal rule

Lists

Ordered and unordered lists.

Ordered Lists

Add a number with period next to it then add a space.

Markdown	Rendered
1. First 2. Second 3. Third	First Second Third

Unordered Lists

Add a - with a space after it.

Markdown	Rendered
- First - Second - Third	First Second Third

Blockquotes

Add > in front of your content.

> This is a block quote

Rendered:

This is a block quote

Blockquotes with multiple lines

> This is a Blockquote
>
> Continued Blockquote

Rendered:

This is a Blockquote

Continued Blockquote

Nested Blockquotes

> This is a Blockquote
>
> >> Nested Blockquote

Rendered:

This is a Blockquote

Nested Blockquote

Code

Inserting a code block

Markdown	Rendered
``` sudo apt-get install sl ```	sudo apt-get install sl

Implementing langauge support

You can implement language support like code highlights by adding the language name next to your first three back-ticks.

```javascript
function greet(greeting, name){
    return `${greeting} ${name}!`
}
```

Rendered:

function greet(greeting, name){
    return `${greeting} ${name}!`
}

You can repeat the same with PHP, Python, or Go.

Links

Links can be created by adding link name between two brackets then follow it by the URL between two parentheses

This is a link to a really great video [The Art of Code]("https://www.youtube.com/watch?v=6avJHaC3C2U")

Rendered:
This is a link to a really great video The Art of Code

Best Practices 👏

Dont't do this ❌	Do this ✔️
[link](https://www.example.com/my great page)	[link](https://www.example.com/my%20great%20page)

Images

You can add images by adding an exclamation mark (!), with an alternate text after it (in case the image couldn't load or for people with visual problems) between two brackets, followed by the URL between two parentheses.

![Beautiful Illustration](https://images.unsplash.com/photo-1530628442364-48f5567cce00?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=700&q=80)

Rendered:

You can also link to an image by enclosing the image tags in two brackets with an exclamation mark (!) after the first bracket, followed by the URL between two parentheses.

[![How to simplify your life](https://images.unsplash.com/photo-1493723843671-1d655e66ac1c?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1050&q=80)](https://medium.com/swlh/simplify-your-life-the-art-of-questions-3282d6723533)

Escaped Characters

Using characters that are related to Markdown inside your text by adding a backslash () in front of your character.

\- Escaped
- Not Escaped

Rendered:
- Escaped

• Not Escaped which results to a list item being rendered

You can realize the not escaped resulted to a list item being rendered

List of Escaped Characters

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

Tables

To create tables you add a pipe symbol (|) for rows and three or more hyphens (---) for columns.

| Table Head | Table Head |
| ----------- | ----------- |
| Table Body | Table Body |
| Table Body | Table Body |

Rendered:

Table Head	Table Head
Table Body	Table Body
Table Body	Table Body

Creating tables can be very time consuming. I recommend using Tables Generator to generate Markdown Tables easily. Another easy way is to use HTML tables as Markdown supports HTML. More on that later.

Strikethrough

You can do strikethrough by adding two tilde symbols (~~) before and after the text.

~~Strikedthrought~~ text

Rendered:
Strikedthrought text

Emojis

You can add emojis by simply...adding emojis. Most Markdown Applications understand emoji characters. You can also use their shortcode.

I am enjoying this blog so far :smile:

Rendered:
I am enjoying this blog so far 😄

HTML

Most Markdown Applications support HTML. HTML can be a lot easier with creating tables and adding images.

This is <strong>HTML</strong>

Rendered:
This is HTML

So Yea! That's about Markdown. I didn't cover everything but I am proud to say i covered most things.

Additional Resources to learn

Here are a bunch of resources you can learn Markdown from.

• Markdown Guide

If you liked the blog make sure to follow me for more blogs soon. Have a great day and goodbye! 👋

Comments

[Pacharapol Withayasakpunt]

Being less opinionated, I am looking for RST tutorials, actually.

Also, regarding markdown, I really like markdownlint (VSCode Extension).