How to Write a README.MD File for Your Project
A README.MD file is an important file to include in your project. It helps others to understand your project clearly. Also, it’s a sign of a good project. Nowadays, it is almost mandatory to write a README
file for any project.
So What is a Readme File?
It’s a text file that includes the necessary information about your project to be understandable. You can write it in any text editor. But nowadays, it is preferable to write it in a markdown language.
What Is the MarkDown Language?
It is a method for writing documents clearly and easily. The markdown formatted document will publish as plain text with any indication of the tags or formatting instructions.
What Does a Readme File include?
- Description of the project.
- Table of the content.
- Examples and screenshots of the outputs.
- The technologies used with links to their websites.
- Information about how to use the repository.
- Resources.
- How to set up the repository locally.
- It will be great to have an online website that users check the result.
- License.
- Also, a significant section will be how others can contribute to your repository.
The Syntax for Writing a Readme File:
There is a syntax we need to follow to make our file clear for the reader.
We will cover the most used syntax.
- Add a Header
There are many levels of header styling as in HTML language. To add a header to your file, you need to include the #
sign before the text
# This is the header
The result will be an H1 header to add a sub-header you can add multiple #
## This is the h2 header
### This is the h3 header
#### This is the h4 header
##### This is the h5 header
###### This is the h6 header
2. Make Text a Bold/Italic Text
We use **text**
or __text__
to make it bold. Make sure there is no space between the star sign and the text. Also, use *text*
or _text_
to make the text italic.
3. Add a Link to Your File
The format is:
[your link name](the actual link)
The result will be
4. Add a List to the File
To add a list, use numbers for an ordered list and use *, -
for an unordered list.
5. Add an Image to Your File
You can add an image to your file in the same way you add it to your HTML file.
<img src='project-img/home.png' width='600' height='400'>
Or
![you got it ](https://sayingimages.com/wp-content/uploads/You-Got-It-meme.jpg)
6. Add Blockquote to the File
Use >text
to add a blockquote to your readme file.
7. Use backticks to add inline code.
8. Add a block of code using Ellipsis
.
9. Add a horizontal line using triple dashes.
10. To support translation for the right to left languages like the Arabic language, you need to insert ‫
before your text or use dir='rtl'
in a div block that surrounds your text
Useful Tools to Help You Writing a Readme
File:
- Common mark and StackEdit: which is an online editor to help you write and view the file.
- Markdown Shortcuts: which is an extension for writing the MD file in “VS studio.”
Wrap up: We mentioned the most used commands for writing a README
file. Also, we described the contents of the file. If you think there is another essential command, please refer to them in the comments👇.