An Informative guide to Markdown

An Informative guide to Markdown

This blog would help you to create your own readme file using markdown syntax in your GitHub Projects.

What is a Markdown?

Markdown can be defined as a plain text formatting syntax used to write content on the web. It is a lightweight markup language that you can use to add formatting elements to plaintext text documents.

It’s commonly used by writers and programmers to write quickly without having to take time using the formatting toolbar of text editors. Many developers like writing in markdown because it gives them fine-grained control over their text and code.

The markdown syntaxes are combinations of special characters with plain texts.

Flavors of Markdown

There are different flavors of markdown available today. For example, GitHub has been using its version of Markdown, where they have added some extra formatting. However, most of the syntaxes work across all the flavors.

It’s your job to master whatever flavor of Markdown your application has implemented.

How to create a Markdown file?

To work with markdown, simply create a text file and save the text file with the .md extension. After that, you'll be able to apply markdown syntax.

How do you use Markdown?

To use Markdown, we just need to apply simple tags to your text.

Let’s learn formatting techniques that will get you started with Markdown in no time.

Table Of Contents

  • Headers
  • Emphasis
  • Lists
  • Links
  • Images
  • Code and Syntax Highlighting
  • Tables
  • Blockquotes
  • Horizontal Rule
  • Line Breaks
  • YouTube Videos

1. Headers

Any line which is prefixed with a # symbol is converted into a heading. The number of hashes indicates the level of the heading.

# H1 Heading
## H2 Heading
### H3 Heading
#### H4 Heading
##### H5 Heading
###### H6 Heading

output

H1 Heading

H2 Heading

H3 Heading

H4 Heading

H5 Heading
H6 Heading

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1 Heading
==============

Alt-H2 Heading
--------------

Alt-H1 Heading
==

Alt-H2 Heading
--

output

Alt-H1 Heading

Alt-H2 Heading

Alt-H1 Heading

Alt-H2 Heading


2. Emphasis

If you want to put emphasis on a word, make use of the (*) asterisk symbol or (_) underscore symbol.

A single asterisk (*) or underscore (_) will italicize the text and a double asterisk (*) or double underscore (_) will make the word bold.

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

syntax

*Italics*

_Italics_

**Bold**

__Bold__

***Bold Italics***

___Bold Italics___

~~Strike this.~~

output

3. Lists

There are two types of lists.

  • Unordered List
  • Ordered List

3.a.Unordered List

To create an unordered list of items, you can use the hyphen(-) or asterisk(*) and space as a prefix to the list item, as shown below:

- list item 1
- list item 2
  - nested list item 1
  - nested list item 2
- list item 3

Or

* list item 1
* list item 2
  * nested list item 1
  * nested list item 2
* list item 3

output

  • list item 1
  • list item 2
    • nested list item 1
    • nested list item 2
  • list item 3

Or

  • list item 1
  • list item 2
    • nested list item 1
    • nested list item 2
  • list item 3

3.b. Ordered List

To create an ordered list of items, add list items with the prefix 1. and followed by a space.

1. list item - one
2. list item - two
    1. nested list item - one
    2. nested list item - two
3. list item - three

Or

1. list item - one
1. list item - two
    1. nested list item - one
    1. nested list item - two
1. list item - three

output

  1. list item - one
  2. list item - two
    1. nested list item - one
    2. nested list item - two
  3. list item - three

Or

  1. list item - one
  2. list item - two
    1. nested list item - one
    2. nested list item - two
  3. list item - three

syntax

[LINK_TEXT](LINK_URL)

Here are some examples on how to create links

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself].

URLs in angle brackets will automatically get turned into links. 
<http://www.example.com>

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

5. Images

To insert an image to your Markdown file, add an exclamation mark (!) at the beginning followed by square brackets to add the image alt text inside that, and finally add the URL or path to the image inside the parentheses.

Make sure to not leave any space between the exclamation mark, square brackets, and parentheses!


Inline-style: 
![alt text](https://play-lh.googleusercontent.com/JKzSZ8dRSeN1SENxZMulZABnssSRgGXwrDgqCquDcLbzgxGCDhogGwzYPIyrWt1-igI=w240-h480-rw align="left")

Reference-style: 
![alt text][logo]

[logo]: https://play-lh.googleusercontent.com/JKzSZ8dRSeN1SENxZMulZABnssSRgGXwrDgqCquDcLbzgxGCDhogGwzYPIyrWt1-igI=w240-h480-rw "Logo Title Text 2"

output

Inline-style: alt text

Reference-style: alt text

6. Code and Syntax Highlighting

6.a Inline Code

The inline code syntax uses the backtick symbols(``) around the code to highlight it.

syntax

`inline code`

output

inline code


6.b Code Block

To display any block of code, simply wrap the code block with (```)

syntax

` ` `programming language name

    Write your code here...

` ` `

Example

` ` `javascript
function print() {
 console.log('Hello World');
}
` ` `

output

function print() {
 console.log('This is is a JavaScript Code Block');
}

7. Tables

The table header and the rest of the rows are separated by | ----------- | ----------- | Each of the table cells in a row must be enclosed like | CELL_TEXT |

| S.No | Name |
| ----- | ------ |
|    1    |   Ravi   |
|    2    | Gopal  |
|    3    | Hitesh |

output

S.NoName
1Ravi
2Gopal
3Hitesh

8. Blockquotes

To write a quote(or blockquote) use the > symbol with space as a prefix to the text.

> Don’t tell people your plans. Show them your results.

output

Don’t tell people your plans. Show them your results.

9. Horizontal Rule

To create a horizontal line in markdown we use three or more Hyphens(-) or Asterisks(*) or Underscores(_).


---

Hyphens

***

Asterisks

___

Underscores

output


Hyphens


Asterisks


Underscores

10. Line Breaks

To create a line break we use one line space between lines.

if we write lines without space between them, then they will be considered as one line.

This is paragraph one.
This is paragraph two.

output

This is paragraph one. This is paragraph two.


To create a line break we use space between them

This is paragraph one.

This is paragraph two.

output

This is paragraph one.

This is paragraph two.


11. YouTube Videos

They can't be added directly but you can add an image with a link to the video like this:

<a href="https://www.youtube.com/watch?v=LOjU3jWiXtI&t=189s" target="_blank"><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1611413734917/au5rxuv_8.jpeg?auto=compress,format&format=webp" 
alt="IMAGE ALT TEXT HERE" /></a>

IMAGE ALT TEXT HERE

Or

Or, in pure Markdown

[![IMAGE ALT TEXT HERE](https://cdn.hashnode.com/res/hashnode/image/upload/v1611413734917/au5rxuv_8.jpeg)](https://www.youtube.com/watch?v=LOjU3jWiXtI&t=189s)

IMAGE ALT TEXT HERE

Closing

I hope that you’ve found this blog and examples on Markdown are helpful! If you have any questions or feedback, feel free to leave a comment below 😊