DEV Community

loading...
Cover image for Markdown: The second step to writing your Blog/Documentation

Markdown: The second step to writing your Blog/Documentation

Mayank Yadav
Everything from design to deployment. Master of bland summaries.
・Updated on ・5 min read

The first step is sitting down and writing it. I'm serious Karen. Stop watching that TV show and start writing. 😜

As per Wikipedia,

Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.

It is much easier as compared to HTML as the latter is quite verbose and not easy to read with all the tags. Let's take a look at how it's done.

NOTE: Markdown may have different flavors, i.e., it may be parsed differently on different platforms.

Paragraph and line breaks

Markdown does not trouble you too much with paragraphs and line breaks. Just press and enter (or return) and start writing. Just like writing an email.

Headers

We get 6 different sizes for headers Just like HTML. The number of #'s you precede the text with is the header size.

# This would be an h1 header
### This would be an h3 header
###### This would be an h6 header

Result:

h1 header text

h3 header text

h6 header text

Emphasize Text

Bold: Surround the text to be bolded by two asterisks(**) or two underscores(__).
Italics: Surround by a single asterisk(*) or underscore(_)
Strikethrough: Surround the text with two tildes (~~)

**This is some bold text**
__This is also bold text__
*This text is in italics*
_And so is this one_
_This_text_won't_be_emphasized
*Here's the best __of both the worlds__*
~~Hello! I'm Darth Maul~~

Result:

This is some bold text*
This is also bold text
This text is in italics
And so is this one
This_text_won't_be_emphasized
*Here's the best __of both the worlds
_*
Hello! I'm Darth Maul

NOTE: Markdown does not allow underlines between the texts. Probably because it affects the readability. Another reason is maybe that underlined texts could be misunderstood for links.
However, we can use line breaks and have underlines for headings. Let's see.

Horizontal Lines

At the start of the line, we can put ___ or *** and the press enter↡ (or return) to get a horizontal line break.
We can make an underlined heading by using = (for H1 heading) or - (for H2 heading) below the heading text.

___
I'm a sandwich
***
This is h1 heading
===
This is h2 heading
---

Result:


I'm a sandwich


This is H1 underlined heading

This is H2 underlined heading

Block Quotes

We can add block quotes by starting our line with >. We can also chain block quotes by increasing the number of >.

> This is the end, beautiful friend  
> This is the end, my only friend  
> > The end of our elaborate plans  
> > > The end of everything that stands  
> The end

Result:

This is the end, beautiful friend

This is the end, my only friend

The end of our elaborate plans

The end of everything that stands

The end


We can end the blockquote with an additional enter↡ (or return).

Lists

Ordered lists are very simple. Just do the numbering as you'd do on a notepad.
We can create unordered lists using the plus (+), minus (-) or the asterisk (*)
Use the Tab key to indent and do list nesting.

1. Go downstairs
2. Ignite the engine
3. Roam aimlessly
* Try Gatsby
- Write an article on Hooks
    + Learn GraphQL
        + Dive deep into MongoDB

Result:

  1. Go downstairs
  2. Ignite the engine
  3. Roam aimlessly
  4. Try Gatsby
  5. Write an article on Hooks
    • Learn GraphQL
      • Dive deep into MongoDB

Task Lists

Task Lists are basically lists with a checkbox. They can be implemented using square brackets.
([ ]) for incomplete
([x]) for complete

[x] Create a plan for the week
[ ] Exercise
[ ] Get groceries

Result:

  • [x] Create a plan for the week
  • [ ] Exercise
  • [ ] Get groceries

Code Blocks

Code blocks can be created by enclosing the paragraph/code with three backticks.
We can also highlight the code as per the language by writing the language name after the first set of three backticks
To use inline code, enclose the code with a single backtick.

Alt Text

Result:

if (!hungry) {
 code();
} else {
 orderFood();
}
typeof NaN === 'number' // true
Infinity === 1/0        // true
0.1 + 0.2 === 0.3       // false

We must use for...in to iterate objects and for...of for arrays.

Tables

Tables in Markdown are created using pipes(|).
Create the first row of headers enclosed and separated by pipes.
Fill the second row with hyphens(-).
Use colons(:) with hyphens to set alignment for the cells in the column.
Colons on left of hyphens for left-aligned, on the right for right-aligned and on both the end for center-aligned.

|Toy Story Movies|Year of release|Rating (Rotten Tomato)|
|:---------------|:-------------:|-----------:|
|Toy Story|1995|100%|
|Toy Story 2|1999|100%|
|Toy Story 3|2010|98%|
|Toy Story 4|2019|97%|
Toy Story Movies Year of release Rating (Rotten Tomatoes)
Toy Story 1995 100%
Toy Story 2 1999 100%
Toy Story 3 2010 98%
Toy Story 4 2019 97%

We can also use inline markdown properties in the table cells.

Links

Links can be created using the below format.

 [<1. Link Text>](<2. The actual link> <3. Title for the link>).

We can also create internal links, to link within a page.

No one really follows me on [Twitter](https://twitter.com/_mayank_09 "Please follow me. Please follow me. Please follow me.").
You know what happened to [Darth Maul](#Emphasize Text "He got sliced.")

Result:

No one really follows me on Twitter.
You know what happened to Darth Maul

Images

Inserting an image is very similar to inserting a link.

![<1. Alt Text>](<2. Path to image> <3. Optional Title>)
!["Hello World"](https://thepracticaldev.s3.amazonaws.com/i/yo9k0p5d6rk0fdj5q6xi.gif "When you successfully print Hello World")

When you successfully print "Hello World"

Emoji πŸ˜„

Emojis are simple to implement, but it's hard to really remember them.
I usually refer to this link whenever I need to. It has almost all the codes for emojis you can possibly use.

Can you guess the movie: :boy: :older_man: :car: :watch:

Result

Can you guess the movie: πŸ‘¦ πŸ‘΄ πŸš— ⌚

Highlight

To highlight a text, enclose it with two equal to signs (==)

Look if you had one shot or one opportunity  
==To seize everything you ever wanted in one moment== 
Would you capture it? Or just let it slip?

The bad news is Dev.to does not support == for highlighting.
The good news is, we can use plain HTML in Markdown too. HTML <mark> tag does the job of highlighting really well.

Look if you had one shot or one opportunity  
<mark>To seize everything you ever wanted in one moment</mark>
Would you capture it? Or just let it slip?

Result:

Look if you had one shot or one opportunity
To seize everything you ever wanted in one moment
Would you capture it? Or just let it slip?

Conclusion

There is a lot more in Markdown but this shall be enough to get you through.

If you think Markdown is not worth your time or if you keep forgetting the syntaxes, you should try Typora. It lets you create Markdown with a really interactive GUI.

Also, you can edit markdown online and watch the effects side by side using StackEdit or Dillinger

You can always refer to this article or some other links below:
Markdown Guide
Markdown Guide Extended Syntax
Github Guides: Mastering Markdown

If you are going to write an article on dev.to, do check out Dev.to Editor Guide

Thanks for reading. πŸ’™

Discussion (0)

Forem Open with the Forem app