• What is Markdown

"Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.(...)
John Gruber created the Markdown language in 2004 in collaboration with Aaron Swartz on the syntax, with the goal of enabling people "to write using an easy-to-read and easy-to-write plain text format (...)"."
Markdown on Wikipedia

• Use Markdown

Markdown is useful in GitHub and other version control softwares, as well as in Slack, Discord...

It helps you display your content with more accuracy and style it your own way

It's especially handy to create professional and polished README files 🙌for your GitHub repositories

• Typing text and creating line breaks and paragraphs in Markdown

- If you type this:

You'll get something that will look like this below in Markdown:

Probably not what you expected 🤔

- Also, if you type this:

You'll get something that will look like this below in Mardown:

Probably not what you expected either ☹️

- To get a simple line break like this:

You have two options:

• Add two spaces at the end of the first line
• Add a <br> tag at the end of the first line

- To create a new paragraph, you must leave an empty line (2nd example above)

• Just like in HTML, there are 6 levels of titles in Markdown

Typing this:

Will look like this below in Markdown:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Tip: there is a shortcut for Headings 1 and 2

- For Heading 1, typing this:

Will produce a Heading 1 like this below in Markdown:

Heading 1

- For Heading 2, typing this:

Will produce a Heading 2 like this below in Markdown:

Heading 2

• To create an horizontal divider in your page, Markdown has an option equivalent to the HTML <hr> tag, only a bit thicker

Typing three or more hyphens:

Or typing three or more asterisks:

Or typing three or more underscores:

Will produce a line like this below in Markdown:

• There are three main ways to add style to text in Markdown

- To add italic effect, you can type one underscore before and after your text:

Or type one asterisk before and after your text:

- To add bold effect, you can type two underscore before and after your text:

Or type two asterisks before and after your text:

Tip: to help recognize different style easier and faster, it is stongly suggested to use different notation for italic and bold

1. One underscore for italic and double asterisks for bold
2. One asterisk for italic and double underscores for bold

To combine them, typing this:

Will look like this below in Markdown:

Combined style with both italic and bold: combined, or combined as well 👏👏👏

- To add strikethrough effect, you can type two tilde before and after your text:

- Some more styling in the HTML in Markdown Section

• Markdown allows you to showcase some text as a "blockquote"
These are all about adding a grey left border to the text and dealing with line breaks

Typing this:

Will look like this below in Markdown:

- In case you want your quote on two or more lines (not paragraphs), remember the first section about how to break lines without creating a new paragraph, and either add two spaces or add a <br> tag at the end of the first line.

Typing this:

Will look like this below in Markdown:

- In the case your quote is longer than one line, typing this:

Will look like this below in Markdown:

- In case you want to add the name of the author on the last line, typing this:

Will look like this below in Markdown:

Note: you can also style your quote text with italic, bold or strikethrough, and you can add links or images inside.

Typing this:

Will look like this below in Markdown:

• In Markdown, you can create ordered or unordered lists, as well as nested ordered or unordered lists

- You can create unordered list by using a "-" or a "*" in front of each item

Typing this:

Or typing this:

Will look like this below in Markdown:

• item
• item
• item

- You can create ordered list by using numbers

Tip: no need to number your items yourself, Markdown will do it for you 😉

Typing this:

Or typing this:

Will look like below this below in Markdown:

1. item 1
2. item 2
3. item 3

- You can also create nested ordered or unordered lists (up to three levels)

For unordered lists, typing this:

Or typing this:

Or typing this:

Or mixing "-" and "*" and "+"

Will look like this below in Markdown:

• Category 1
  • item 1
  • item 2
• Category 2
  • item 1
  • item 2

Note: nested ordered lists work the same 😎

More details here

• You can add two categories of code blocks to your Markdown 👩‍💻👨‍💻

- Inline code blocks use back-ticks

Typing:

Will look like this below in Markdown:

This is some inline code

- Blocks of code are either indented with four spaces, or fenced by lines with three back-ticks ( ```) but only the latter solution allows for syntax highlightning where it's supported so that it's considered "best practice"

Typing:

Will look like this below in Markdown:

• Tables in Markdown are a great way to organise your informations

Tables are not a part of Markdown spec, but thet are widely supported, and especially on GitHub

The creation of tables in Markdown looks exactly like drawing with dashes (-) and pipes (|)
You may also use colons to align columns.

Typing this:

Will look like this below in Markdown:

Tip: there are three best practices to remember

• There must be at least 3 dashes separating each header cell. Colons to align columns count as dashes
• The outer pipes (|) are optional
• You can use inline Markdown in cells

This means typing this:

Will look like this below in Markdown:

• There are two sorts of links in Markdown

- Plain external links, also called "inline style"

-- The easiest way to create a link is to just type an url with or without the <>

Tip: this also works for email addresses

Typing:

Or:

Will give the same result as an <a> tag:

https://wwww.google.com

-- Yet, Markdown has its own syntax for adding links that looks like this: [text](href "alt"), the "alt" text being optional and displaying in a bubble in Markdown (i.e. the equivalent of the title attribute for the <a> tag in HTML)

In our case, it would be typing:

To get:

Google

Or:

To get:

Google Homepage

Tip: you can format links with italic or bold just like normal text (see Section 5)

- Recurrent external links, also called "reference style"

Let's imagine you're writing a book in Markdown and you need to use the same link in different places, it's convenient to use one reference for all of these identical links

In such a case, you can call a link many times like this:

And add the url at one place, usually at the end of your file, like this:

Note: it seems there's no equivalent to the target="" attribute in Markdown in GitHub, even with using an HTML <a> tag and manually adding the attribute, which means your links will open in the same window when clicked upon

• Adding images in Markdown is quite the same as adding links

Adding images into Markdown uses the same syntax as for links with a "!" in front

Typing this:

Will give the result below in Markdown:

Tip: it works as well for animated gifs 🎬

Tip: to add a link to an image, you must combine image and link and use the following syntax

Note: just like in links, you can also add an "alt" text with this syntax ![text](href "alt")

Note: the links "reference style" system (see section 10) can also be used for images you'd have to use many times in a file

• Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown's formatting syntax

Typing this:

Will look like this below in Markdown:

*This is non-bold text between asterisks*

This works for the following characters:
\ (backslash), `(backtick), * (asterisk), _ (underscore), {} (curly braces), [] (square braces), () (parenthses), # (hash mark), + (plus sign), - (minus sign, or hyphen), . (dot), ! (exclamation mark)

• As already seen, there are many occasions to use HTML in Markdown to create specific results
Here are a four more I use very often

- Undeline text with using the <ins>to be underlined text</ins> HTML tag

This is using a semantic tag in place of CSS, but that's the only way to get it right in Markdown 🤷

- Center text or titles or images (or animated gif pretty often in my case) with inserting the style attribute align="center" in your HTML tag

- Deal with YouTube videos

They cannot be directly added but you can add an image with a link to the video:

-- either with the usual Markdown syntax [](url of the link on the image)

-- or with HTML tags <a> and <img> to access the "width" and "height" attributes to style the image

More details here

- Create tables of contents with inner links tag

There are two ways to do that:

-- using an <a> HTML tag to add a "name" attribute to each title,

-- adding a {#custom-id} to each title,

and then creating a simple link to each "name" attribute in your table of contents

More details here

Note: you can add HTML inside Markdown, but you cannot add Markdown inside HTML

Typing this:

Will look like this:

I want this text to be in **bold**

(No bold effect created since the Markdown was inside the HTML tag)

• GitHub being a big user of Markdown, it has its own version of the Markdown syntax called GitHub Flavored Markdown or simply GFM
Here are five main GFM features

- Task Lists

A task list mixes a list (ordered or unordered) with squared brackets and will look like HTML checkboxes

Typing this:

Will look like this:

- Usernames @mentions

Typing an @ symbol, followed by a username, will notify that person
You can also mention @teams within an organization

- Issues and Pull requests references

Any number that refers to an Issue or Pull Request will be automatically converted into a link

- SHA references

Any reference to a commit’s SHA-1 hash will be automatically converted into a link to that commit on GitHub

- Emojis

GFM supports emojis with this syntax: :star: will automatically turn into ⭐

More details in the links below:

Emoji Markdown cheatsheet with Search bar

Other Emoji Markdown cheatsheet

• Markdown around the web 🌏

• Markdown in Wikipedia
• Official Markdown website by John Gruber
• Markdown Guide
• Markdown Wiki
• Markdown Mark by Dustin Curtis
• GitHub Guide - Mastering Markdown
• GitHub - Writing on GitHub
• GitHub Article - Basic Writing and Formatting Syntax
• NodeSchool "How to Markdown" tutorial
• "Mastering Markdown" by Wes Bos
• Markdown tutorial for beginners