Devansh Soni's Blog
Write your readme.md file for Github like a Pro

Write your readme.md file for Github like a Pro

Writing Markdown Files

Devansh Soni's photo
Devansh Soni
·

4 min read

Every Freelancing Project or an Industrial Project requires a file that guides users to the Project about its functionality or maybe a sequence of steps that are required to complete the project set up in their environment.

Readme.md on Github or any SCM Repository is mainly required to guide any user in order to project setup or to understand Product's functionality.

In this article, we will be learning about how we can write this readme file and what syntactical sugar is required while writing these .md (Markdown) files.

Following are some building blocks of writing any file cleanly or in a formatted manner :

  • Headings
  • Content Decoration such as Bold, Italic, Underlined etc
  • Lists
    • Unordered Lists
    • Ordered Lists
  • Links
  • Images in Document

Headings

  • We are having different levels of Heading which are directly proportional to their size.
  • # Main Head -- Single # is required to format text to its maximum Length or to write Heading at level 1 we use Single #
  • ## Sub Head -- ## is required to write Heading at level 2 or a kind of subheadings we use ##

We can extend these levels of headings till level 6 of six #s in Markdown

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Note: Please make sure to add one space after #s combinations otherwise it will not work

Text Decoration in Markdown Files

Text Decoration in documents includes marking a word as Bold, Italic, and striping a text. Below are the easy and straightforward ways by which we can perform the above operations on a text.

  • Bold Text -- ** Your Text **.
  • Italic Text -- * Your Text * or _Your Text_
  • Strikethrough a text -- $~~100~~ $80

Lists in Markdown Files

Lists in a document are more necessary in order to make our document more concise, readable, and understandable. Following is the explanation of writing Ordered Lists and Unordered Lists in a Markdown Document.

  • Unordered Lists: These listing are not having any order specified in their list items.
    • In order to start a list item in an unordered list we should start our sentence with - and a space after this.

We can also create a sub-list of a list by nesting - under one another. Consider below example for reference. 

  - Backend Technologies
    - Node JS
    - Django

Above will result in the below listing.

  • Backend Technologies
    • Node JS
    • Django
  • Ordered List: These listings mainly specified order in their list items. Order can start Alphabetically, Numerically. Consider the below example to check how we can make an Ordered List :
1. One
1. Two
1. Three

or 

1. One
2. Two
3. Three

Both of the above snippets will result in the below output

  1. One
  2. Two
  3. Three

In order to create a nested list, we can simply do that by adding that list under the main list item in an indented manner. Consider the below example for reference

1. One
  1. One (A)
  1. One (B)

It will result in the below output :

  1. One
    1. One (A)
    2. One (B)

While writing a document we might need to insert a third-party link in it so get more references about the terms used in the document.

We can use the below syntax in order to insert a link in our document.

[Link Text](Link URL "Hover Text of Link" )
[Google](https://www.google.com "Google Link is here")

We can also insert an Image in our Markdown document to make it a bit attractive using

![Image Alt Text](Path to Image)
![Python](https://upload.wikimedia.org/wikipedia/commons/c/c3/Python-logo-notext.svg)

Above will insert a Python Logo in our Document.

I hope the above points will help you to write and format your readme.md Markdown file for your Repository better and make it more understandable and concise.

READMEGitHubrepositorymarkdown cheat sheetmarkdown