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
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.
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.
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.
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 |  | An image  |
| Link+images | [](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 |
|
| Ordered Lists | 1. Item a 2. Item b |
|
| Mixed Lists | 1. Item 1 * item 1a |
|
| 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) | |
| Strike through | ~ |
|
| Tables | | Tables | Are | Cool | |----------|:-------------:|------:| | col 1 is| left-aligned | $1600 | |  |
Note: **Footnote** actually doesnt render properly in table (and github preview), 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.
-
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 )
I had such a pain making the above table possible