Nov 24th, 2022

How to write a README.md file?

Author Picture

Dhairya Shah

Software Engineer

In this article, you will learn what is a markdown file and how to write the markdown. Most of the time, you will find markdown files in GitHub repositories such as README.md, CONTRIBUTING.md, or CODEOFCONDUCT.md.

What is a README file?

In simple words, a README file that guides users with a detailed explanation of the project/repository.

It describes the documentation with guidelines explaining the usage of the project. Usually, it describes the installation instructions.

It is very important to know how to document a readme as a developer, because:

README files are written in markdown language. So, let’s understand what is markdown.

What is markdown?

Just like HTML, markdown is a lightweight markup language for creating formatted text using plain text. Markdown is actively used by developers and bloggers. Developers use markdown to write documentation as we discussed earlier README. It converts some plain text to the desired format in HTML. The simplicity and ease to understand are making the markdown more popular.


To create a markdown file, name the file with the .md extension. For example, readme.md.


Just like HTML, markdown has 6 levels of headings i.e h1 to h6. In markdown, we use # to add the heading. The number of the hash symbol will increase the heading type.

# This is an H1
## This is an H2
### This is an H3
#### This is an H4
##### This is an H5
###### This is an H6


No special rules, just need to write simple text to write paragraphs,

This is an example of simple text

Adding links to the markup looks like the following,

[link text](URL)

For example,


Bold Text

Bold text can be written by enclosing the text with double asterisks **.

**Hello World**

Italic Text

Italic text can be written by enclosing the text with a single asterisk *.

*Hello World*


Strikethrough text can be written by enclosing the text with the double tilde symbol ~~

~~This is a strikethrough text~~


Adding images to markdown looks like following

![image alt text](image path)

Note: Don’t get confuse the image markup with link markup. Images have an exclamation mark ! at the start.



Tables can be written like the following,

|Name|Email|Address|      <====== This is the heading of the table
|----|-----|-------|      <====== This is the separator.
|John|[email protected]|Address1| <=== This is the table body.


If you want to write quotes just add a > symbol at the beginning of the line.

> This is a quote


Code can be written by enclosing the text with a backtick `

`await hello()` we are calling an async function


Codeblock can be written like following, Codeblock


The list can be written as order and unordered, for example:

1. Javascript
2. VS Code
3. OS
   * MacOS
   * Linux
* Dog
* Cat
* Lizard

Horizontal line

A horizontal line in the markdown file can be added simply by --- or ***:

Hello World

hello world

Note: *** is for a thicker line.

Wrap Up

There you have it, everything you need to improve your README files, or even get started with writing your first one.

Now you will confidently write the amazing READMEs for amazing projects.

There are many tools on the internet that allow you to write README for your next project. In case you want to check them out:

Thanks for reading

Follow me on Twitter

Thanks for reading!