Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/luong-komorebi/Markdown-Tutorial
A comprehensive guide to Markdown / Introduction to Markdown
https://github.com/luong-komorebi/Markdown-Tutorial
guide markdown markdown-flavour markdown-tutorial
Last synced: 3 months ago
JSON representation
A comprehensive guide to Markdown / Introduction to Markdown
- Host: GitHub
- URL: https://github.com/luong-komorebi/Markdown-Tutorial
- Owner: luong-komorebi
- Archived: true
- Created: 2016-06-26T16:28:47.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-31T17:21:20.000Z (almost 2 years ago)
- Last Synced: 2024-05-18T19:19:05.005Z (6 months ago)
- Topics: guide, markdown, markdown-flavour, markdown-tutorial
- Homepage: https://luong-komorebi.github.io/Markdown-Tutorial/
- Size: 121 KB
- Stars: 533
- Watchers: 13
- Forks: 800
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- jimsghstars - luong-komorebi/Markdown-Tutorial - A comprehensive guide to Markdown / Introduction to Markdown (Others)
README
# 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](https://github.com/LewisVo/Markdown-Tutorial/blob/master/Translation:Spanish.md) 🇪🇸.
- Portuguese version available [here](https://github.com/LewisVo/Markdown-Tutorial/blob/master/README_pt-BR.md) 🇵🇹.
- French version available [here](https://github.com/luongvo209/Markdown-Tutorial/blob/master/README_fr.md) 🇫🇷.
*******
Tables of contents
1. [What is Markdown?](#whatismarkdown)
2. [Why use Markdown?](#why)
3. [Tools for Markdown](#tools)
4. [Markdown Syntax](#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](https://github.com/jgm/CommonMark/wiki/Markdown-Flavors).*
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*](https://stackedit.io)** : 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*](http://dillinger.io/)** : Online tool, support live view (split screen) and export to html. Nothing too special but very neat and handy.
* **[*Typora*](https://www.typora.io/)** : 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*](https://atom.io/)** : 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*](https://chrome.google.com/webstore/detail/minimalist-markdown-edito/pghodfjepegmciihfhdipmimghiakcjf?hl=en)** : Chrome app. Works everywhere if you have Chrome installed ( this is my favorite one).
* **[*Macdown*](http://macdown.uranusjr.com/)** : best for Mac.
* **[*MarkdownPad*](http://markdownpad.com/)** : best for Windows.
* **[*Remarkable*](https://remarkableapp.github.io/)** : best for Linux.
* **[*GITBOOK*](http://www.gitbook.com/)** : 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](https://daringfireball.net/projects/markdown/syntax) . 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](http://www.github.com) |
| Images | \ | An image  |
| Link+images | \[\\](url to a page)\] | Click me [](https://www.youtube.com) |
| 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[^1]. With some additional text after it. |
[^1]: My footnote reference.
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:
```
* Markdown does support Emojii :laughing: :laughing: :kissing_heart: :innocent: :green_heart: ( get some emojies [here](http://www.emoji-cheat-sheet.com/) )
* You can use \
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](http://www.markdowntutorial.com).
* Footnotes and syntax highlighting are not part of the original markdown and are only supported by certain flavors of markdown (Feedback from [Sean Brody](https://goo.gl/ASZwEn))
* 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 [](https://github.com/) [](https://github.com/)
[](https://github.com/)
[](https://github.com/)
[](https://www.linkedin.com/)
[](https://github.com/)
( get some badges [here](https://shields.io/) )
* 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
```diff
- text in red
+ text in green
! text in orange
# text in gray
@@ text in purple (and bold)@@
```
* Add beautiful note or warning section into markdown GitHub:
> **Note**:
> **Warning**:
* 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](https://mermaid-js.github.io/)
- Class diagram
```mermaid
classDiagram
class Duck{
-weight
+swim()
+quack()
}
```
- Sequence diagram
```mermaid
sequenceDiagram
participant dotcom
participant iframe
dotcom->>iframe: loads html w/ iframe url
```
- Flowchart
```mermaid
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.