You will learn everything about Readme file like how to create a readme file, readme file exam, template, syntax, format, editors, Github readme.md file and many more.
Are you wondering about what is readme file?
Readme file is a file that gives an introduction about your project.
- It provides a guide on how to use it, what are the requirements to run the project successfully.
- Contains all about the project.
- Provides user guidance in a more enhanced way.
And it contains the main objective of the project.
The readme file gives a rich look to the text by using MarkDown Language.
What is Markdown?
Markdown is a lightweight markup language. Markdown file is just the normal text which represents it as the rich text. And the extension of the MarkDown file is .md.
Where does Readme.md file normally found?
We use the readme file as a Markdown file which is readme.md. You can find these readme.md file in repositories like Github, Gitlab, and Bitbucket repositories.
How to create Readme.md file?
You can create a readme file like you create your text file.
You need to change the extension from .txt to .md and follow the rules given below.
And you can use it as a readme file in repositories of the version control system or anywhere you want.
Now let's see how to write a readme.md file.
How to write Readme.md file
There are many ways by which you can write your Readme.md file.
Ways to write Markdown files
One way is to use any Text Editors which you use for coding and in which you are comfortable with.
Letting it be Visual Studio Code, Sublime, Bracket, or Atom. Feel free to use any text editor you like.
You can use a dedicated Markdown editor for generating readme-files like Typora. You can even make use of online editors like Stackedit, Dillinger. By default, they provide you with the format of markdown syntax already written in it.
Readme.md file Syntax/Format
To write Readme file in markdown language you don't need any prior knowledge in programming languages. Just follow the rules given below and you will be good to go no other requirements are needed.
Rules for Readme MarkDown file
The Readme file example which you can see below is the execution of Visual Studio Code text editor.
HEADINGS
For Headings, you just need to add Hash symbols as per the heading type. Don't forget to give a white space after the hash symbol.
You can use 'n' number of hash for heading 'n'.
Example: 1 hash for heading 1, 2 hash for heading 2, etc.
# Heading1 ## Heading2 . . ###### Heading6
Note: You can use a maximum of 6 hashes as there are 6 variations of heading.
 |
| Headings |
NORMAL TEXT
You don't need any kind of special symbol for Normal text.
You can directly write the text and it will represent it as normal text only.
Normal Text
 |
| Normal Text |
BOLD or STRONG TEXT
For Bold or Strong text we add two Asterisk (star) symbols at the beginning & end of the text without any white spaces.
Note: We can use Underscore sign in place of Asterisk.
**Bold or Strong** __Bold or Strong__
 |
| Bold or Strong Text |
ITALIC TEXT
For Italic text, we add a single Underscore symbol at the beginning & end of the text without any white space.
_Italic_
 |
| Italic Text |
STRIKE THROUGH TEXT
For Strikethrough the text we give two Tilde symbols at the beginning & end of the text without any white spaces.
~~Strike~~
 |
| Strike-Through text |
HORIZONTAL LINE or DIVIDER
To give a Horizontal line between two sections or lines use Divider by using three Underscore or Asterisk (Star) symbol after the section or line you want to use the Divider. If you use the Asterisk (Star) symbol you will get a little thicker line as compare to Underscore symbol.
___ ***
 |
| A horizontal line or divider/separator |
LISTS
You can create Ordered, Unordered List through the MarkDown Language.
1. To represent the Ordered list we use the Numbers, as usual, followed by a dot, a white space.
If you make a mistake in the serialization of the list in a correct manner you don't have to worry.
The interpreter will take care of the correct serialization and your list will have the correct numbering.
1. One 2. Two 3. Three 4. Four
You can even create sub-lists by giving the indentation of three White Spaces at the beginning of the lines.
1. One
2. Two
1. First child of Two
2. Second child of Two
 |
| Ordered list |
2. To represent the Unordered list you can either use a Hyphen, an Asterisk followed by white space.
- One - Two * One * Two
You can create sub-lists inside the Unordered list similar to the Ordered lists.
We just have to give indentation of two White Spaces at the beginning of the lines of the list.
- One - First Child - Second Child - Two * One * First Child - Second Child * Two
Note: Changing the symbol from Hyphen to Asterisk or vise-versa you will notice a gap difference in the list. And this will take place only with the Parent list and not with the Child list.
 |
| Unordered list |
QUOTES
To represent a Quote in your MarkDown file use the GreaterThan symbol followed by white space.
> Hard work can beat Talent.
 |
| Quote |
CODE
To represent a code you can use a pair of Back Quote symbols. The Code should be in between the Back Quotes.
`Code`
 |
| Code |
CODE BLOCK
To represent Lines of Code or Block of Codes use three pairs Back Quote symbols.
Give three opening Back Quotes, give the Programming Language just after the opening three Back Quotes without any space.
Now start writing the code from the next line.
After completing your code, end it by giving the closing three Back Quotes in the next line.
```Language Block of Code ```
 |
| Code Block |
HYPERLINKS
To represent Hyperlinks you have to use the combination of Square Brackets and Parentheses/Round Brackets, without any white space.
Inside Square Bracket, give the Link name which is the name of the link.
Inside Parentheses/Round Brackets, give the target URL which is the target address.
[Google](https://www.google.com)
You have an option to give a Link title which will be visible on hovering the Link.
To give Link title add Inverted comma with the target URL inside the parentheses
Note: There will be a white space between the target URL and the link title.
[Google](https://www.google.com "Homepage")
 |
| Hyperlink |
IMAGES
To add Image you need to have the address of the image present on the web. The syntax is similar to the syntax of Hyperlink.
We use the combination of Square Brackets and Parentheses/Round Brackets.
We add an additional Exclamation mark sign at the beginning of the line without any white space anywhere.
Followed by Image name inside the Square Brackets and Image URL inside the Parentheses.
We can even add the image title as we did in the Hyperlinks.
For link title, add a white space followed by inverted commas with the image title inside the Parentheses.
 |
| Image |
TABLES
To create Tables in the Readme MarkDown file, we use the combination of Pipe and Hyphen sign. There are three parts to the table.
First is the table head in which we write the headings inside the pair of pipes. The table head will be in bold in the actual view of the readme file.
| Name | Class | Roll No |
Second is the separator which separates the table header with the table body. The separator will be in between the table head and table body.
For separators, we give Hyphens inside the pair of pipes you can add hyphens to enhance the look.
Note: There are no such fix rules to give a specific number of hyphens. It is compulsory to give a minimum of one hyphen in the pair of pipes.
| ---- | ----- | ------- |
Third comes the table body which is like the table head. The only difference will be in the text. It will be in normal text and not in bold text. The text must be in the pairs of pipes.
| John | 9 | 2 | | Jane | 8 | 9 |
 |
| Table |
Github readme best practices
It is a good practice to create the readme file at the beginning of the project.
It is better to proceed along with the project and note down the instructions side by side.
By using the above rules, you can write a killer readme file for your projects. Write readme file and help your audience to understand your project easily
It will definitely take you a step ahead from other programmers.
It is always a good habit to provide your project with the readme file. I hope this post has helped you in some way. If you have any queries feel free to contact me.
Here are some slides for the Syntax/Format of markdown file.
0 Comments