Demystifying Markdown for GitHub

Demystifying Markdown for GitHub

The path for better documentation

Varun Joshi's photo
Varun Joshi

Published on Mar 4, 2021

5 min read

All of us have wondered how to write the Readme.md file while understanding the GitHub workflows, how does the documentation work, and how to write a wiki for the project. The Answer is MarkDown

markdown-512.webp MarkDown language helps up in documenting the project in a better way, it is simply the lightweight markup language that helps in converting the text into markup language(html) which is easier to read. Lets us understand how to write this markdown language.

1. Heading

markdown supports different sizes of headings, which helps differentiate between the heading, title, and subtitle.

# I am highest size heading ( <h1> tag )
## I am a little smaller than the first ( <h2> tag )
### I am smaller than the second size ( <h3> tag )
#### I am smaller than the third size  ( <h4> tag )
##### I am smaller than the fourth size ( <h5> tag )
###### I am the smallest size of the heading. ( <h6> tag )

This is how it looks.

I am highest size heading

I am a little smaller than the first

I am smaller than the second size

I am smaller than the third size

I am smaller than the fourth size
I am the smallest size of the heading.

2. Linking Images

can be Linked following way using CDN link

!(alt-name of image)[path of the image]

Link Can be used to represent different attachments and third-party software.

[Text that appears](Link)

4. Emphasis on the text

Making text Bold by enclosing them between two underscores or two asterisks.

__making text Bold__

or

**making text Bold**

The text could be made italics when enclosed between one asterisk or single underscores.

*making text Italian*

or

_making text Italian_
_*Bold and italian*_

5. Ordered List

ordered List used to represent different items like the stack, contributor guidelines, guide to starting the project which can be done following way.

1. first Item
2. Second Item 
3. Third Item

6. Unordered List

unordered List used to represent different items which can be done following way.

* Item
* Item 
* Item

7. Quote

> using greater than a symbol to Quote a statement.

These were some of the basic syntax that can be used everywhere. But to make it easy but github provides additional feature like

Task List

Tasklist helps to merge a pull-request submitted, which defines all the new feature added or changes done to source code.

-[X] task 1
-[] Not completed task

Emoji

Github Supports different emojis to make the documentation attractive.

Emojis supported on Github are predefined and enclosed between colon
:name:
:+1:

you can find all the name of the emojis here

markdown preview in vscode.

If you use vscode then you can install this extension Markdown Preview Enhanced written by Yiyi Wang which will make it easier for documentation.

Screenshot from 2021-03-04 08-40-43.png

 
Share this