Markdown Tutorial

Hello, welcome to my tutorial for markdown. 👋

In this tutorial you will learn the most basics things about Markdown. 👩‍🏫👨‍🏫

Spanish version available here 🇪🇸.
Portuguese version available here 🇵🇹.
French version available here 🇫🇷.

Tables of contents

What is Markdown?
Why use Markdown?
Tools for Markdown
Markdown Syntax

What is markdown ?

According to Wikipedia :

Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool by the same name. 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.

SIMPLY: IT'S JUST ANOTHER TYPE OF TEXT FILE, LIKE .txt .doc ....( now it's .md :laughing:) AND IT HAS SOME SPECIAL SYNTAX.

There is no clearly defined Markdown standard. This has led to fragmentation as different vendors write their own variants of the language to correct flaws or add missing features.. A list of markdown flavour is available here.

From now, this guide will mainly focus on Github Flavoured Markdown.

Why use markdown?

Because it's :

EZ : The syntax is so easy that you can learn in a minute or two then write without noticing anything weirdo or geeky.
FAST : It saves time compared to other types of text files/formats. It helps boost the productivity and workflows of writer.
CLEAN : Both the syntax and output are clean, not messy with our eyes and simple to manage.
FLEXIBLE : With just a little set-up, your text will be translated cross any platform out there, editable in any text-editing software and convertible to a wide array of formats.

In short, normal users will find it useful in any cases, especially when you are in need of something better than plain text but less functional than Microsoft Word.
For Developers, if you are lazy to write HTML code , you will love markdown. Moreover, Github and many sites favor markdown for readme file of projects. That means you gonna meet markdown in your life one way or another.

Tools for markdown

As said above, any editors can be used to edit markdown. However, there are a few tools that may be useful for you when it comes to edit markdown.

Stackedit : Ok, you can stop reading right now. Click the link then start your markdown tour in an eziest way ever. Just type normal text then use your mouse, click click done. You dont have to know the syntax. It's good, but it will make you reliant and most developers prefers keyboards.
Dillinger : Online tool, support live view (split screen) and export to html. Nothing too special but very neat and handy.
Typora : Available for Mac and Windows, minimal, distraction free, live view seemlessly, bundled with a lot of other stuffs like Images, Lists, Tables, Code Fences, Math Blocks, YAML, Front Matters,Toc,...
Atom : popular hackable text editor (you may be using this). Yeah, this is versatile. Markdown Support? Just a part of it but is greatly built in.
Minimalist Markdown : Chrome app. Works everywhere if you have Chrome installed ( this is my favorite one).
Macdown : best for Mac.
MarkdownPad : best for Windows.
Remarkable : best for Linux.
GITBOOK : GitBook is a modern publishing toolchain. Making both writing and collaboration easy. It does both support Markdown and have a close relation with the beloved Github.

Markdown Syntax

All Syntax can be found here . It would take a lot of effort to describe syntax in text (they will be formatted) so please consider this table below for the whole basics syntax.

Format	Syntax	Example
Italic	Text	This is italic
Bold	Bold	This is bold
Inline links	[Description text](url here)	A link
Images	![Caption](url to img)	An image
Link+images	[![Caption](url to img)](url to a page)]	Click me
Footnotes	I have more [^1] to say. [^1]: say it down here.	Hey,Please read the note below this table.
Line breaks	Double space + enter
Unordered Lists	* Item1 *Item 2	item1 item2 item3 item4
Ordered Lists	1. Item a 2. Item b	itema itemb itemc itemd
Mixed Lists	1. Item 1 * item 1a	itema item1
Block quote	> Quoted text	Stay Hungry Stay Foolish
Preformatted	Begin each line with,two spaces or more to,make text look,e x a c t l y,like,you,type i,t.	Begin each line with,two spaces or more to,make text look,e x a c t l y,like,you,type i,t.
Code	`Insert Code`	`cout<<"Hello world";`
Code block/ Syntax highlighting	```insert code```	Hey,Please read the note below this table.
Headers	#, ##, ###, ####, #####, ###### (from h1 to h6)	This is a h3 header
Strike through	~~~Insert text here~~~	~~I am dead~~
Tables	\| Tables \| Are \| Cool \| \|----------\|:-------------:\|------:\| \| col 1 is\| left-aligned \| $1600 \|
Footnotes	Footnote[^1] [^1]: Text reference	Here is a simple footnote¹. With some additional text after it.

Note: **Footnote** actually doesnt render properly in table, but it kinda looks like this

The same goes for block code/syntax hightlighting. It kinda looks like this picture :

These characteristics are dependent upon each markdown flavour.

Useful notes :

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. One commonly used backslash escape character is : \
So? \*This\* isnt italic anymore but is surrounded by literal asterisks.
Youtube videos require some additional work.

They can't be added directly but you can add an image with a link to the video like this:
<a href="http://www.youtube.com/watch?feature=player_embedded&v=YOUTUBE_VIDEO_ID_HERE
" target="_blank"><img src="http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg" 
alt="IMAGE ALT TEXT HERE" width="240" height="180" border="10" /></a>

Markdown does support Emojii 😆 😆 😘 😇 💚 ( get some emojies here )
You can use <br/> tag to force line break.
Double space then enter if you want to make a new line if there is trouble making new lines.
Seeing is not as good as practicing. You can either create a markdown file for yourself to practice or do it online here.
Footnotes and syntax highlighting are not part of the original markdown and are only supported by certain flavors of markdown (Feedback from Sean Brody)
Any URL (like http://www.github.com/) will be automatically converted into a clickable link.
Markdown table support is designed to handle most tables for most people; it doesn’t cover all tables for all people. If you need complex tables you will need to create them by hand or with a tool specifically designed for your output format.
Using image and links, you can create some colorful assets at render time. Badges like this are typical examples that you can find all over Github ( get some badges here )
Using code block syntax with diff language to generate colored text. There are still some limitations such as can not style the text inside and few colors. This can be applicable when you want to highlight some note or to show difference between two code block

- text in red
+ text in green
! text in orange
# text in gray
@@ text in purple (and bold)@@

In markdown file on Github, with code block syntax and Mermaid language specifed, we can draw many kinds of diagram. More syntax and sample diagrams here

Class diagram

classDiagram
    class Duck{
     -weight
      +swim()
      +quack()
    }

Sequence diagram

sequenceDiagram
    participant dotcom
    participant iframe
    dotcom->>iframe: loads html w/ iframe url

Flowchart

  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;

Author: Vo Tran Thanh Luong. Also, I would like to thank all the contributors/translators for your work making this greater.

My footnote reference. ↩

jackie4u/markdown-tutorial