DEV Community

Cover image for A comprehensive guide on markdown
Madhav Gupta
Madhav Gupta

Posted on

A comprehensive guide on markdown

#markdown #tutorial

Hello everyone. Hope you are doing great.
I am Madhav Gupta and this post will be dedicated to markdown.
By the end of this post, I really hope that you'll be having more than enough knowledge of markdown to use it in your daily life.

Let's start with a bunch of questions,

Q- What is Markdown?
A- Markdown is a lightweight markup language with plain text formatting syntax. In simple terms, markdown is a way to style text on the web having simple syntax than HTML.

Q- Why bother learning it?
A- There can be a lot of reasons to learn Markdown, I will be listing some of them

  • Easy to learn and easy to read
  • Used in Github documentation
  • can be easily converted into other formats
  • you might start writing posts on dev.to after learning it

Enough with the questions, let's get on board.

  • Headers

There are six types of headings ranging from H1 to H6. You can use headers in two ways.
First - Using a # followed by the text
Second - Inserting 3 ===(for H1) or ---(for H2) below the text. The downside of going through this path is that you can only use H1 and H2. Hence I'll recommend sticking to the former way.

Examples -

# H1
## H2
### H3
#### H4
##### H5
###### H6
Enter fullscreen mode Exit fullscreen mode

(spaces given for readability)

H1

H2

H3

H4

H5
H6 
H1
===
Enter fullscreen mode Exit fullscreen mode

H1 

H2
---
Enter fullscreen mode Exit fullscreen mode

H2

  • Text Formatting

Formatting text in markdown is very easy. You can change the feel and look of your text by making it italic, bold or striking it.

Examples -

_italic_ or *italic*
Enter fullscreen mode Exit fullscreen mode

italic

__bold__ or **bold**
Enter fullscreen mode Exit fullscreen mode

bold

~~strikethrough~~
Enter fullscreen mode Exit fullscreen mode

strikethrough

Since there are two ways for text to be italic and bold. So in order to avoid the confusion, I will recommend using italic and Bold. This will help you in reducing the ambiguity and confusion you might face while styling your text.

  • Lists

You always make lists for one purpose or another. You can use both unordered and ordered lists in markdown according to your needs

Unordered Lists
Here is the syntax for an unordered list in markdown. You can replace + with * or -

+ First item in the unordered list
+ Another item in the unordered list
+ one more item
Enter fullscreen mode Exit fullscreen mode

Above code gets converted into this.

  • First item in the unordered list
  • Another item in the unordered list
  • one more item

Ordered Lists

1. The first item in the ordered list
2. The second item in the ordered list
3. The third item in the ordered list
Enter fullscreen mode Exit fullscreen mode

Instead of going with the above syntax, you can also go with

1. The first item in the ordered list
1. The second item in the ordered list
1. The third item in the ordered list
Enter fullscreen mode Exit fullscreen mode

and both the examples will result in the following list

  1. The first item in the ordered list
  2. The second item in the ordered list
  3. The third item in the ordered list
  • Links

You can use links in markdown by using the following syntax.

[Text](the link you want to relate with text)
Enter fullscreen mode Exit fullscreen mode

Example -

[Link to my first article](https://dev.to/madhavgupta/visual-studio-code-and-its-magic-1a2m)
Enter fullscreen mode Exit fullscreen mode

Link to my first article

Both ways can be used to reference external links but I will recommend the latter one for enhanced readability. Instead of using [1], you can use anything such as [meow] or [blah] and it will work fine.
If there is no text, then you can highlight the link be using <link>.

  • Images

Images can be embedded in a markdown document by using the following syntax. Not only images, but you can also use gifs too by using the same syntax.

![Alt text for your image](Link of the image)
Enter fullscreen mode Exit fullscreen mode

Example -

![](https://images.unsplash.com/photo-1515524738708-327f6b0037a7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1050&q=80)
Enter fullscreen mode Exit fullscreen mode

  • Horizontal Rule

Depending on how your parser makes the horizontal rule, it is always great to have some of them in your article/documentation.

Example-

--- or *** or ___
Enter fullscreen mode Exit fullscreen mode
  • Code block

Add code blocks to your posts/articles by surrounding your code with three
backticks and if you want to highlight syntax, then write the name of language after backticks.

  • Block Quote

Give special emphasis to the quotes to make them stand out.

> Quote
Enter fullscreen mode Exit fullscreen mode

Example -

> “Websites promote you 24/7: No employee will do that.” 
― Paul Cookson
Enter fullscreen mode Exit fullscreen mode

“Websites promote you 24/7: No employee will do that.”
― Paul Cookson

  • Tables

Showing data in tabular form is very convenient and I must say, making tables in markdown is not so pretty. One more thing, the : is responsible for the alignment of the elements in rows. Examples given below will make this statement more clear.

|Songs|Creators|
|:-----|:-----|
|Without Me|Helsey, Khalid and Benny Blanco|
|Hope|Chainsmokers|
|Never Gonna give you up|_I'll leave it here_|
Enter fullscreen mode Exit fullscreen mode
Songs Creators
Without Me Helsey, Khalid and Benny Blanco
Hope Chainsmokers
Never Gonna give you up I'll leave it here 
|Songs|Creators|
|-----:|:-----|
|Without Me|Helsey, Khalid and Benny Blanco|
|Hope|Chainsmokers|
|Never Gonna give you up|_I'll leave it here_|
Enter fullscreen mode Exit fullscreen mode
Songs Creators
Without Me Helsey, Khalid and Benny Blanco
Hope Chainsmokers
Never Gonna give you up I'll leave it here

You can also use the good-old HTML tags(pre, code, img, table) in markdown if you ever feel the need to. Markdown is great and it makes sure that your entire focus remains on the content.

If you knew it all, congratulations. This post might act as a refresher for you. If it is the other way around, Hope it helps.

So, that's it for today. I'll be back soon with another one(open for ideas).
Hope you like it.
Have a great day. Thanks.

Top comments (0)

Read next

jonathanfarrow profile image

Predicting House Prices with XGBoost in Node.js

Jonathanfarrow -

clericcoder profile image

Mastering Trace Analysis with Span Links using openTelemetry and Signoz (A Practical Guide,Part 2)

Abdulsalaam Noibi -

shelar1423 profile image

How I Cloned Myself with LLMs to Work 24/7 – Even While I Sleep

Digvijay Shelar -

clericcoder profile image

Mastering Trace Analysis with Span Links using OpenTelemetry and Signoz (A Practical Guide, Part 1)

Abdulsalaam Noibi -