Markdown - The Absolute Beginner's Guide

Subscribe to my newsletter and never miss my upcoming articles

Markdown is a lightweight markup language used by technical professionals to create/edit technical documents and create rich text using a plain text editor. With Markdown, you write text in a plain text editor (such as vi, Emacs, nano, notepad), inserting special characters to create headers, boldface, bullets, paragraphs, links, images and so on. This article would provide a comprehensive guide to help you get started using markdown.

Fun fact: This article is written in markdown.

Why Markdown?

The Markdown language was created in 2004 with readability as its key design goal. Its variants are currently used by renown sites like Slack, Github, BitBucket, Reddit, StackExchange and Hashnode to create rich text and facilitate discussions between users. As Markdown has a very gentle learning curve, its basic concepts can be mastered within minutes. For example, the following text is a simple document formatted with Markdown.

### Markdown has a gentle learning curve.
Markdown parsers convert markdown files into **HTML** or **XHTML**. Browsers then display _resulting_ HTML files to *readers*.

The rendered version of the markdown file above is shown below.

Markdown has a gentle learning curve.

Markdown parsers convert markdown files into HTML or XHTML. Browsers then display resulting HTML files to readers.

Wow image Note: StackEdit is an online markdown playground where you can practice markdown concepts you would learn in this guide.

Headers

Headers are formatting conventions used in websites, magazine articles, scientific journals, technical documentation and newspapers to draw attention to a section. There are six types of headers as shown below in decreasing sizes:

Header one

Header two

Header three

Header four

Header five
Header six

Conventionally, in websites, headers help to optimize accessibility by acting as titles and subtitles above sections and subsections. While HTML tags <h1> <h2> <h3> <h4> <h5> <h6> are used to create headers in HTML, the same convention can be achieved in Markdown by prefixing the phrase with a hash (#). The number of hashes should correspond to the size of the header you want. That is — for h1, use one hash, for h3, use three hashes. The following shows the header types example above in markdown

# Header one
## Header two
### Header three
#### Header four
##### Header five
###### Header six

Good Gif

Italicizing and Bold

We would proceed to learn two other formatting conventions: italics and bold. Conventionally, these formatting conventions draw attention to formatted text. In HTML, texts are italicized with tags <i> and <em> and are bolded with tags <b> and <strong> notwithstanding the semantic implication of individual tags. However, the same formatting convention can be achieved in Markdown. To italicize in Markdown, you surround texts with an underscore (_). The following example shows a markdown file with italicized text:

_Italicizing text in Markdown is easy_. Ta-da!

The rendered markdown document is shown below.
Italicizing text in Markdown is easy. Ta-da!

Similarly, to make text bold in Markdown, you surround words with two asterisks (**).

This is a **bold text**.
**Another bold text**

The rendered markdown document is shown below.
This is a bold text. Another bold text

Blockquotes

Blockquotes are a formatting convention used to call attention to a quote from another source or a contextually important block of text. To create a blockquote in Markdown, prefix each line/sentence with the "greater than" caret (>). In the following example, a quotation is turned into a block quote

> While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms.

The rendered markdown document is shown below

While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms.

If a quote spans multiple paragraphs, caret characters (>) should be placed at the start of each line. In this case, blank inter-paragraph lines must also be prefixed with a caret to ensure common grouping of the entire blockquote.

> This is the first line of this multi-line quote.
>
> Oh! There's a blank line above also prefixed with a caret.
> This is the second line of this multi-line quote.

The above is rendered as shown below

This is the first line of this multi-line quote.

Oh! There's a blank line above also prefixed with a caret.
This is the second line of this multi-line quote.

Links can also be created in Markdown. There are two different linking conventions in Markdown:

  • Inline links
  • Reference links

However, both conventions render the exact same way. To create an inline link, wrap the link text in brackets ([]), and the link in parentheses (()).

This is an inline link example  
[Visit Example](https://example.com)

The above is rendered as shown below.
This is an inline link example
Visit Example.

However, in reference links, the links are text references to a dictionary of links somewhere in the document.

[Here is a reference link][First Reference]
[Here is another reference link][Second Reference]
[This links to Google][Google]
[This links to my portfolio][Portfolio]

[First Reference]: https://github.com
[Second Reference]: https://stackoverflow.com
[Google]: https://google.com
[Portfolio]: https://ifeanyimuogbo.tech

The markdown is rendered as shown below.
Here is a reference link
Here is another reference link
This links to Google
This links to my portfolio

As demonstrated in this example, reference links do not appear in the rendered markdown. They are defined by providing the tag name wrapped in brackets, followed by a colon, followed by the corresponding link.

Images

Image creation in Markdown follows nearly the same syntax used in link creation. The only difference between both is that images are prefixed with an exclamation mark (!) while links are not. Conversely, two conventions exists for creating images in markdown:

  • Inline image link
  • Reference image link

To create an inline image link, prefix a link with an exclamation mark.

![Black Labrador Retriever](https://images.unsplash.com/photo-1571772805064-207c8435df79?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=300&q=80)

Black Labrador Retriever
The image link text does not display as it becomes the image alt text. Although it isn't compulsory to supply an alt text, it optimizes your image's accessibility and hence makes your website/document accessible to your audience (including visually impaired people).
Similarly, to create a reference image link, assign a bracketed dictionary text as image link.

![Adult brown chow-chow][Dog]  

[Dog]:  https://images.unsplash.com/photo-1559515796-f24c8045ea9d?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1055&q=80

Adult brown chow-chow

Lists

Lists can also be created in Markdown. Two routinely used types of list exist:

  • Ordered list
  • Unordered list

Both types can be created in markdown. The unordered list, <ul> in HTML, can be created by prefixing each item in the list with an asterisk (*).

* First Item
* Second Item
* Third Item
* Fourth Item
* Fifth Item

The markdown is rendered as shown below.

  • First Item
  • Second Item
  • Third Item
  • Fourth Item
  • Fifth Item

The ordered list, <ol> in HTML, can be created by prefixing each item with its corresponding number (the exact way it renders).

1. Item One  
2. Item Two
3. Item Three
4. Item Four
5. Item Five

The markdown is rendered as shown below.

  1. Item One
  2. Item Two
  3. Item Three
  4. Item Four
  5. Item Five

Lists can be nested by indenting each asterisk one space more than the preceding item.

* First Item
 * Nested in First Item
* Second Item
 * Nested in Second Item
  • First Item
    • Nested in First Item
  • Second Item
    • Nested in Second Item

Stay with me gif

Paragraphs

Paragraphs in Markdown can be formatted with any of these.

  • Hard breaks
  • Soft breaks

Hard breaks are accomplished by inserting a new line after a paragraph the usual way while soft breaks are accomplished by inserting two spaces after each new line. Although it is impossible to display either a new line or space in these code blocks, 'new line' would be represented with [new line] and space would be represented with [space].

This paragraph is formatted with a hard break.
[new line]
Another line in this paragraph
[new line]
Yet another line in this paragraph

This paragraph is formatted with a hard break.

Another line in this paragraph

Yet another line in this paragraph

This paragraph is formatted with a soft break.[space][space]
Another line in this paragraph[space][space]
Yet another line in this paragraph

While a hard break breaks the togetherness, a soft break preserves togetherness in a block of text.

What's Next?

Congratulations gif Congratulations: You are now grounded in the basics of the Markdown markup language. However, it is important to understand that we have only covered the basics of what can be accomplished with Markdown. There are quite a number of extended implementations of Markdown that supports formats like tables, footnotes and more. These nonstandard implementations are outside the scope of this article as this article only attempts to cover the basics of standard markdown. A sequel to this article would explore these implementations.

I hope you enjoyed reading this article and learned a thing or two. If you did, drop your comments and reactions, share this post and join my newsletter to get notified when I write a sequel.

Bolaji Ayodeji's photo

Love this, thanks for sharing!

Ifeanyi Muogbo's photo

Glad you loved it.

Osaro Onaiwu's photo

Henceforth, I'll employ markdowns in my posts. Thanks.

Show +1 replies
Peter Thaleikis's photo

Yeah, I thought the same: used it without knowing :D

Ifeanyi Muogbo's photo

Yeah, Peter Thaleikis It so happens that Hashnode uses Markdown 😀

Sahil Kazi's photo

Well written Ifeanyi Muogbo

Amarachi Winner's photo

This was such an interesting read.. easy to grasp and practice immediately. Thank you so much

Ifeanyi Muogbo's photo

You're welcome, Amarachi. Really glad you found this interesting and easy to grasp.

Chisom Aniekwensi's photo

It was an interesting read tbh, didn't know much of what you talked about but now I know better.

Ifeanyi Muogbo's photo

Great to hear. Glad you found this helpful. I'd be writing a sequel to this soon, and would be glad if you stop by to check that when I do.

Edidiong Asikpo's photo

This is an interesting breakdown of Markdown. I love it.

Ifeanyi Muogbo's photo

Really glad you loved this. I'd be glad to have you stop by when I update more interesting content.