How to Write Markdown
Tags: markdown, markdowncheatsheet, markdownsyntax, documentation
Published: 2024-01-17 14:46:45

---
title: How to Write Markdown
published: true
date: 2023-11-29 14:13:15 UTC
tags: markdown, markdowncheatsheet, markdownsyntax, documentation
canonical_url: https://ogagaonuta.hashnode.dev/how-to-write-markdown
---

![Markdown_HowTo](https://cdn.hashnode.com/res/hashnode/image/upload/v1701264135486/4d91731b-4661-41a0-81bb-5928664485ff.png?w=1600&h=840&fit=crop&crop=entropy&auto=compress,format&format=webp)

## Introduction

In this article, readers will learn how to write in Markdown and use it in formatting their documents.

A different range of creators can make use of Markdown. For software developers, the file with the information about your projects, like the `README.md` file is written in Markdown. Technical and content writers can also use Markdown to write documentation, blogs, and other write-ups.

This article helps you understand how to write in Markdown.

## Table of Content

* [Prerequisite](#prerequisite)
* [What is Markdown?](#what-is-markdown)
* [Formatting in Markdown](#formatting-in-markdown)
    * [Headers](#headers)
    * [Paragraphs](#paragraphs)
    * [Bold](#bold)
    * [Italics](#italics)
    * [Lists](#lists)
        * [Ordered Lists](#ordered-lists)
        * [Unordered Lists](#unordered-lists)
    * [Code](#code)
        * [Inline Code](#inline-code)
        * [Multi-line Code](#multi-line-code)
    * [Blockquotes](#blockquotes)
    * [Links](#links)
        * [Inline Links](#inline-links)
        * [Reference Links](#reference-links)
    * [Images](#images)
        * [Inline Images](#inline-images)
        * [Reference Images](#reference-images)
    * [Table](#table)
    * [The "Escape Character"](#the-escape-character)
* [Conclusion](#conclusion)
    * [Resources](#resources)

## Prerequisite <a name="prerequisite"></a>

To follow along with this article;

- download and install a text editor able to render Markdown, like [_Visual_ _Studio Code_](https://code.visualstudio.com/download), or

- use an online editor, like [_Dillinger_](https://dillinger.io/)

## What is Markdown? <a name="what-is-markdown"></a>

**Markdown** is a way to write and format content for the web. It uses special syntax to format documents. Writing in Markdown differs from other applications that use **GUI** (Graphical User Interface) to highlight and format text, like _Microsoft Word_, and _Google Docs_.

Some text editors provide **WYSIWYG** _(What You See Is What You Get)_ features that render and display the Markdown formatted text as you edit them, like _Visual Studio_ _Code, Notepad++, Ghostwriter, etc_. These text editors might require an extension/plugin to display Markdown.

The file extension for markdown is _.md_ or _.markdown_. Say you have a file named `my_file`, to make it a Markdown file, you save it as `my_file.md` or `my_file.markdown`.

Markdown was created by **John Gruber** in **2004**.

## Formatting in Markdown <a name="formatting-in-markdown"></a>

Special characters are used to format Markdown files, _i.e._ making text _italics_, **bold** , and so on. These special characters are highlighted below:

> **TO SPARK YOUR INTEREST, THIS ARTICLE WAS WRITTEN IN MARKDOWN.**
> 
> **NOTE:** The rendered Markdown is shown after every code block.

### Headers <a name="headers"></a>

To indicate a _header_ in Markdown, begin the line with a _hash_ (`#`) sign. There are six levels of headers in Markdown, and the number of `#` signs beginning the line marks the level of the header. Each header must be separated with blank lines.

```md
# Header LEVEL 1

## Header LEVEL 2

### Header LEVEL 3

#### Header LEVEL 4

##### Header LEVEL 5

###### Header LEVEL 6

```

RENDERED OUTPUT

![Markdown_Header](https://cdn.hashnode.com/res/hashnode/image/upload/v1701261863709/2e72ef9f-60da-4a66-88b2-5337c2863c8e.png)

### Paragraphs <a name="paragraphs"></a>

To write _paragraphs_ in Markdown, you separate each paragraph with a _blank line_. Some Markdown renderers require that you end each paragraph with _two spaces_ (`[][]`) to mark the end of the paragraph, and to also indicate blank lines, like _GitHub Flavored Markdown_.

```md
This is a paragraph,
and this is part of the same paragraph.
[BLANK LINE]
This is another paragraph.[][]
This is yet another paragraph.[][]
[][]
And this is also another paragraph.

```

RENDERED OUTPUT

![Markdown_Paragraph](https://cdn.hashnode.com/res/hashnode/image/upload/v1701261893923/4c52dc38-8aa9-47bd-870e-0c9d434c84cd.png)

> `[]` in the example code above represents a **space** from pressing the " **SPACEBAR**" key

### Bold <a name="bold"></a>

To **bolden** a text, surround the text with **two asterisks** (`**`) or**two underscores** (`__`). Be consistent with whichever you choose.

```md
Surround text with **two asterisks** or __two underscores__ to format as bold.

```

RENDERED OUTPUT

![Markdown_Bold](https://cdn.hashnode.com/res/hashnode/image/upload/v1701261959417/844531c3-1721-481a-9706-f15915fe04ff.png)

### Italics <a name="italics"></a>

To display text as _italics_, surround the text with _one asterisk_ (`*`) or _one underscore_ (`_`). Whichever you decide to use, try to be consistent with it.

```md
Surround text with *asterisk* or _underscore_ to format as italics.

```

RENDERED OUTPUT

![Markdown_Italics](https://cdn.hashnode.com/res/hashnode/image/upload/v1701261999653/182d59ba-b875-4db3-b232-a3c41f1a6bef.png)

### Lists <a name="lists"></a>

_Lists_ are used to present text in steps. They are usually separated by blank lines for readability sake. There are two main types of lists as explained below:

#### Ordered Lists <a name="ordered-lists"></a>

Lists are presented in an order when the next step cannot be done before the previous step. For example, to put on your trainers when you want to go for a run, you don't wear your shoes before wearing your socks, it has to be done the other way around. To indicate an ordered list, begin each line with a number (`1, 2, 3, etc`) and a period (`.`) sign.

```md
Follow this routine when exercising:

1. Warm-up
2. Low-intensity exercises
3. High-intensity exercises
4. Warm-down

```

RENDERED OUTPUT

![Markdown_Ordered_Lists](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262032903/50b56627-e621-43ea-ab61-6ab59b018c14.png)

#### Unordered Lists <a name="unordered-lists"></a>

Lists that don't require any particular order are labelled **unordered**. For example, when shopping for groceries, you can decide to get the third, or seventh item on the list provided you are on the aisle where the item is displayed before picking up the first item. To display an unordered list, begin each line with an _asterisk_ (`*`), a _dash_ (`-`), or a _plus sign_ (`+`).

> **REMEMBER** : Be consistent with whichever format you choose.

```md
Provisions List

* Peanut Butter
* Cookies
* Cereal

Body Care List

- Hair Cream
- Body Cream
- Deodorant

Cloth List

+ Shirts
+ Jeans
+ Socks

```

RENDERED OUTPUT

![Markdown_Unordered_Lists](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262099939/580e239e-7609-4cb6-9da6-6f8a7f9b62e0.png)

Lists can also be nested in lists. To do this, indent the nested list by at least _4 spaces_ or _1 tab_.

```md
How to:

* Develop a program
    1. Think out the algorithm
    2. Write the pseudocode
    3. Code the program

* Prepare a cereal
    * Get the cereal
    * Get the bowl and cutlery
    * Pour the milk
    * Pour the cereal
    * Add sweeteners

```

RENDERED OUTPUT

![Markdown_Nested_Lists](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262155882/d8bf8176-6462-4dff-b7f0-a7d694455ff0.png)

> Note how you can get the bowl and cutlery before the cereal, or pour the cereal before the milk, for unordered lists.

### Code <a name="code"></a>

`Code` is highlighted and formatted differently from every other text. It is mainly used to display programming languages, but can also be used to display special text. The two ways to display text as code are shown below:

#### Inline Code <a name="inline-code"></a>

To display `code` inline, that is, without breaking the flow of the document, surround the code with _backticks_ (`` ` ``).

```md
To display output in Python, use the `print()` function.

```

RENDERED OUTPUT

![Markdown_Inline_Code](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262215235/8c9568c4-488e-4cc8-b394-8b1b22751585.png)

#### Multi-line Code <a name="multi-line-code"></a>

To display `code` in more than one line, as a block, surround the lines with _three backticks_ or _three tilde_ (`~~~`) signs. To format the code as a specific programming language, or as a text, add the language file extension after the first three backticks or tilde signs.

~~~md
Displaying output in Python

```py
print("Hello, world!")

```

~~~

```md
Formatting text as bold in Markdown

~~~md
What **country** do you hail from?

~~~

```

RENDERED OUTPUT

![Markdown_Code_Block](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262286921/9744c535-0cf6-4998-8d0a-7acf2663e2cd.png)

### Blockquotes <a name="blockquotes"></a>

_Blockquotes_ are displayed in a special way to get the reader's attention. It is usually used to indicate important information. To highlight a blockquote, begin each line with the _greater than_ sign (`>`). Blank lines in blockquotes also begin with `>`.

```md
Here are two famous quotes:
> The greatest glory in living lies not in never falling, but in rising
> every time we fall.[][]
> \- Nelson Mandela
>
> The way to get started is to quit talking and begin doing.[][]
> \- Walt Disney

```

RENDERED OUTPUT

![Markdown_Blockquotes](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262315204/82b92e45-3132-4328-83b0-fa9826eab252.png)

> Note the _two spaces_ after the quote to end the paragraph, and the _backslash_ "\" (explained later in this article) used here to prevent the text from becoming a list within the blockquote.

### Links <a name="links"></a>

_Links_ are used to direct users to another location, like another page on the website/document, or another website/document entirely. Links are formatted in two ways:

#### Inline Links <a name="inline-links"></a>

For inline links, the links are shown side-by-side with the text when writing Markdown. To create an inline link, surround the link text with _square brackets_ `[]`, and then follow up with the link surrounded with _parentheses_ `()`. There should be no space between the square brackets and parentheses.

```md
This is a link to my very [first article](https://ogagaonuta.hashnode.dev/python-need-to-know-for-beginners)

```

Clicking on the link text will now point you to the specified link as shown below:

RENDERED OUTPUT

![Markdown_Inline_Link](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262368090/b35b3acf-6dfc-4969-9116-d9fa19c2c335.png)

#### Reference Links <a name="reference-links"></a>

For reference links, a _tag name_ is placed side-by-side with the text. This tag name then points to the link somewhere else in the document. This makes the document readable, by separating the link(s) from the text. It also helps when editing as you only have to correct the link in one place, rather than going through the whole document and correcting the link in several places.

To create a reference link, surround the link text with _square_ _brackets_ `[]`, and then follow up with the tag name surrounded in _square brackets_. There should be no space between the square brackets and the tag name. For a multi-word tag name, use underscores or dashes as a separator.

The tag name can now be pointed to the link anywhere else in the document by specifying the tag name in _square brackets_, followed by a _colon_ (`:`), a _space_, and then the link, all on its line. This is mostly placed at the end of the document.

```md
Click [here][google] to visit the **Google** website.

[google]: https://www.google.com/

```

RENDERED OUTPUT

![Markdown_Reference_Link](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262393669/53293443-7554-4a7e-9360-25dd9b87eb35.png)

### Images <a name="images"></a>

Images can also be displayed in Markdown. Images are formatted the same way as links, with the _one difference_ of beginning each image with an _exclamation mark_ (`!`). The link text is replaced with an _alternate_ _text_ for the image, and the link itself is replaced with a link to the image, either stored locally on your computer or hosted online. As links, there are two ways to format images:

#### Inline Images <a name="inline-images"></a>

To display an image inline, you begin with an _exclamation mark_ (`!`), and then follow the same syntax as the _inline links_ described above.

```md
This is an image of the **Bash _Shebang_**.

![shebang](https://res.cloudinary.com/practicaldev/image/fetch/s--ggy90Gr7--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://dev-to-uploads.s3.amazonaws.com/i/71jsf4ymyf93rz7m45m4.png)

```

RENDERED OUTPUT

![Markdown_Inline_Image](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262418226/baa7189b-0272-47b4-8d30-7c8170d1804b.png)

#### Reference Images <a name="reference-images"></a>

To display an image as a reference, you begin with an _exclamation_ _mark_ (`!`), and then follow the same syntax as the _reference links_ described above.

```md
My present profile picture.

![profile picture][prof-pic]

[prof-pic]: ./images/profile_picture.png

```

RENDERED OUTPUT

![Markdown_Reference_Image](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262442960/4314122f-138a-4008-8c74-bb3cb567670e.png)

### Table <a name="table"></a>

A table is a visual aid arranging elements in rows and columns. Markdown is also able to create tables by using the _pipe_ (`|`) character. Each _column_ is separated by the _pipe_ character, and each _row_ is placed on its line. To separate a header row from the body row, you create a row with each column filled with _dashes_ (`-`)

Columns can be aligned by placing _colons_ (`:`) on the row separating the header and body. By default, columns are left aligned. Put the colons:

- on the _left_ for left alignment

- on the _right_ for right alignment

- on _both sides_ for centre alignment

```md
The Logic **AND** Table

| A | B | A AND B |
| :---- | :---- | :-----: |
| True | True | True |
| True | False | False |
| False | True | False |
| False | False | False |

```

RENDERED OUTPUT

![Markdown_Table](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262483556/4fa48e55-1615-40a4-bd31-250ab47cf398.png)

### The "Escape Character" <a name="the-escape-character"></a>

The _escape character_ is used to prevent the character which follows it from executing its special meaning. It removes the formatting of the character and displays it as plain. The escape character is the _backslash_ (`\`), and it comes in handy when writing in Markdown.

```md
\* is used to begin a list item in Markdown.

\- is also used, it's just based on preference.

The **asterisk \*** is used to format text as bold.

To escape a backtick in an inline code, surround it with two backticks `` ` ``.

The escape character can also escape a backtick, e.g. \`print()\` instead of
`print()`.

```

RENDERED OUTPUT

![Markdown_Escape_Character](https://cdn.hashnode.com/res/hashnode/image/upload/v1701262510312/16bd0ca8-a8b0-478a-9321-94d603cb1692.png)

> Note the use of backticks to escape another backtick. This is a special case.

## Conclusion <a name="conclusion"></a>

I hope you enjoyed reading this article and were able to follow along practically. If you did, you should be able to write in **Markdown** now. Markdown is fun and easy to write.

Highlighted below are links for further reading.

See you in my next article.

### Resources <a name="resources"></a>

- [https://www.markdownguide.org/tools/](https://www.markdownguide.org/tools/)

- [https://www.markdowntutorial.com/](https://www.markdowntutorial.com/)

- [https://www.dotcms.com/docs/latest/markdown-syntax](https://www.dotcms.com/docs/latest/markdown-syntax)

- [https://markdownguide.offshoot.io/basic-syntax/](https://markdownguide.offshoot.io/basic-syntax/)