Markdown Tutorial
# Markdown Tutorial
# 1. Markdown
# Introduction
Markdown is a lightweight markup language that allows people to write documents in an easy-to-read, easy-to-write plain text format.
# Applications
Many websites now widely use Markdown to write help documentation or post messages on forums. For example: GitHub, Jianshu, Zhihu, etc.
# Editor
Recommended: Typora, official website: https://typora.io/ (opens new window)
# 2. Badges
# What Are Badges
Badges are small, elegant icons usually accompanied by related text for supplementary explanation. They can be used for data monitoring, link navigation, and are very expressive.
They are commonly seen on GitHub project pages, but they can appear anywhere images can be displayed.
# Using Badges
- Using in
markdown
Format:
[](hyperlink-url) # A hyperlink wrapping an image
Syntax:
[](https://github.com/xugaoyi)
2
3
4
5
Badge generation website: https://shields.io/ (opens new window)
This document mainly covers Markdown and won't go into too much detail about badges. For a detailed introduction, please click here (opens new window).
# 3. Table of Contents
After setting this up, a table of contents will be automatically generated based on heading levels.
[TOC]
Note: Not supported on GitHub yet.
[TOC]
How to generate TOC on GitHub: https://github.com/ekalinin/github-markdown-toc (opens new window)
For Windows, you need the golang-based tool: https://github.com/ekalinin/github-markdown-toc.go
If you have a Go language compiler, you can try compiling it yourself. Otherwise, you can download pre-compiled binaries directly.
For 64-bit Windows, download: gh-md-toc.windows.amd64.tgz (386 is 32-bit, amd64 is 64-bit)
After extracting, you'll find the file has no extension and can't be recognized. It's actually an exe file, so just add .exe to the end and you're good to go.
Usage:
- First, copy the .md file to the root directory of gh-md-toc.exe
- Open a system command line in that directory and enter: gh-md-toc.exe README.MD to generate the table of contents
- Copy the generated table of contents into the .md file.
Table of contents generated by gh-md-toc:
- 1. Markdown
- 2. Badges
- 3. Table of Contents
- 4. Headings
- Heading 1
# 4. Headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
2
3
4
5
6
# Heading 1
# Heading 2
# Heading 3
# Heading 4
# Heading 5
# Heading 6
# 5. Text
# Paragraphs
Markdown paragraphs have no special formatting; just write text directly. When paragraph indentation is needed, use 2 tabs.
# Fonts
*Italic text*
or _Italic text_
**Bold text**
or __Bold text__
***Bold italic text***
or ___Bold italic text___
2
3
4
5
6
Italic text
Italic text
Bold text
Bold text
Bold italic text
Bold italic text
# Strikethrough
To add a strikethrough to text in a paragraph, simply wrap the text with two tildes ~~ on each side, as shown below:
~~BAIDU.COM~~
BAIDU.COM
# Underline
Underline can be achieved through the HTML <u> tag:
<u>Underlined text</u>
Underlined text
# Text Highlighting
Text highlighting makes inline text stand out, using a pair of backticks.
`html` `css` `javascript`
html css javascript
# Horizontal Rule
You can create a horizontal rule using three or more asterisks, hyphens, or underscores on a line. The line cannot contain anything else. You can also insert spaces between the asterisks or hyphens. Each of the following styles creates a horizontal rule:
***
*****
- - -
----------
2
3
4
5
6
7
# Footnotes
Footnotes are supplementary explanations for text.
[^variable]
Assign value to the variable at the end of the document or another location:
[^variable]: Content displayed in the annotation box
Hover over this > [^hello]
[^hello]: Content displayed in the annotation box
2
3
4
5
6
Note: Not supported in some online previews.
Hover over this > [^hello]
[^hello]: Content displayed in the annotation box
# 6. Lists
# Unordered Lists
Use asterisks *, plus signs +, or hyphens - as list markers:
* Item 1
* Item 2
+ Item 1
+ Item 2
- Item 1
- Item 2
2
3
4
5
6
7
8
- Item 1
- Item 2
# Ordered Lists
Use numbers followed by a . to indicate ordered lists:
1. Item 1
2. Item 2
2
- Item 1
- Item 2
# Collapsible Lists
<details>
<summary>Click to expand/collapse</summary>
Collapsed content
<ul>
<li>1</li>
<li>2</li>
<li>3</li>
</ul>
</details>
2
3
4
5
6
7
8
9
Note: Markdown code inside <details> tags won't render; use HTML code instead, such as ul>li, table, etc.
Click to expand/collapse
Collapsed content- 1
- 2
- 3
Collapsible section with a table
| Category | Examples |
|---|---|
| Personal Pronouns - Subjective | I, you, he, she, they, we |
| Personal Pronouns - Objective | me, you, him, her, them, us |
| Possessive Pronouns | my, his, your, their, hers |
| Demonstrative Pronouns | this, that, these, those |
| Reflexive Pronouns | myself, himself, themselves, yourself, herself |
| Interrogative Pronouns | who, what, which |
| Indefinite Pronouns | some, many, both, any |
| Relative Pronouns | which, who, that |
| Reciprocal Pronouns | each other, one another |
| Conjunctive Pronouns | who,whom,whose,what,which,whatever,whichever,whoever,whomever |
| Substitute Pronouns | one (singular), ones (plural) |
# Checkbox Lists
* [x] Item 1
* [ ] Item 2
* [ ] Item 3
2
3
Note: Not supported in some online previews.
[x] Item 1
[ ] Item 2
[ ] Item 3
# Nested Lists
1. Item 1:
- First nested element of item 1
- Second nested element of item 1
2. Item 2:
- First nested element of item 2
- Third level nesting
2
3
4
5
6
- Item 1
- Nested 1
- Nested 2
- Item 2
- Nested 1
- Nested 2
- Nested 1
# 7. Blockquotes
Blockquotes use the > symbol at the beginning of a paragraph, followed by a space:
> Blockquote
Blockquote
In Typora, pressing Enter automatically extends the blockquote
# Nested Blockquotes
> Level 1
> > Level 2
> > > Level 3
2
3
Level 1
Level 2
Level 3
# Lists Inside Blockquotes
> Lists inside blockquotes
> 1. Item 1
> 2. Item 2
> * 111
> * 222
2
3
4
5
Lists inside blockquotes
- Item 1
- Item 2
- 111
- 222
# Blockquotes Inside Lists
* Item 1
> Blockquote
* Item 2
2
3
Item 1
Blockquote
Blockquote
Item 2
# 8. Code
For inline code snippets in a paragraph, wrap them with backticks (`), example:
`alert()`
alert()
# Code Blocks
Use triple backticks ``` to wrap a code block and specify a language (optional). Specifying the code language enables syntax highlighting.
This code block serves as an example:
```javascript
function test() {
alert('test')
}
```
2
3
4
5
Result:
function test() {
alert('test')
}
2
3
# 9. Links
Format:
[Link text](link-url)
[Link text](link-url, optional-alt)
or
<link-url>
2
3
4
5
6
7
Example:
[Baidu](http://www.baidu.com,'Baidu')
Display link URL directly:
<http://www.baidu.com>
http://www.baidu.com (opens new window)
# Variable Links
Links can use variables instead of URLs, with the variable address appended at the end or elsewhere in the document:
This link uses 1 as the URL variable [Google][1]
This link uses baidu as the URL variable [Baidu][baidu]
Then assign values (URLs) to the variables at the end or elsewhere in the document
[1]: http://www.google.com/
[baidu]: http://www.baidu.com/
2
3
4
5
6
This link uses 1 as the URL variable Google (opens new window)
This link uses baidu as the URL variable Baidu (opens new window)
# Internal Links in GitHub Repositories
You can use relative paths (provided the file exists at that path)
[test](test.md)
2
# Anchor Links
Every heading in this file is an anchor, similar to HTML anchors (#):
[Markdown](#Markdown)
Note: When using anchors with headings that contain punctuation on GitHub, the punctuation is ignored. In this page, writing it this way won't work: [Links](#9-links) Correct format: [Links](#9links)
# 10. Images
The difference from links is the addition of an exclamation mark ! at the beginning:
Of course, you can also use variables for image addresses, just like links:
Here, img is used as the image address variable
Then assign a value (image address) to the variable at the end or elsewhere in the document
![RUNOOB][img]
[img]: https://raw.githubusercontent.com/xugaoyi/image_store/master/blog/md_logo.png
2
3
4
# Image Width and Height
To set image width and height, you can use the <img> tag:
<img src="https://raw.githubusercontent.com/xugaoyi/image_store/master/blog/md_logo.png" width="50px" height="30px">
# Relative Paths and Using Images on GitHub
Whether locally or within the same repository on GitHub, you can use relative paths if the image exists.
Relative path image:
On GitHub, when referencing images from other GitHub repositories, pay attention to the address format: repo-url/raw/branch-name/image-path or https://raw.githubusercontent.com/username/repo-name/branch-name/image-path
or
2
3
4
# 11. Tables
Tables use | to separate cells and - to separate the header from other rows.
| Header | Header |
| ---- | ---- |
| Cell | Cell |
| Cell | Cell |
2
3
4
| Header | Header |
|---|---|
| Cell | Cell |
| Cell | Cell |
Alignment
- -: sets content and header to right-aligned
- :- sets content and header to left-aligned
- :-: sets content and header to center-aligned
| Left-aligned | Right-aligned | Center-aligned |
| :-----| ----: | :----: |
| Cell | Cell | Cell |
| Cell | Cell | Cell |
2
3
4
| Left-aligned | Right-aligned | Center-aligned |
|---|---|---|
| Cell | Cell | Cell |
| Cell | Cell | Cell |
# 12. Emoji
Add colons before and after the English name of an emoji. In Typora, type a colon followed by the first letter to get emoji suggestions.
:smirk:
💋 😸🙈🐴 😏😊😃😄 ☀️
For more emoji names, check: Emoji Cheat Sheet (opens new window)
# 13. Other Tips
# Supported HTML Elements
Tags not covered by Markdown syntax can be used directly as HTML in the document.
Currently supported HTML elements include: <kbd> <b> <i> <em> <sup> <sub> <br> and more, for example:
Use <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> to restart the computer
Use Ctrl+Alt+Del to restart the computer
This is bold text using the b tag
# Escaping
Markdown uses many special characters to represent specific meanings. To display these characters literally, use the backslash escape character:
**Un-escaped asterisks show bold**
\*\* Escaped asterisks display as-is \*\*
2
Un-escaped asterisks show bold ** Escaped asterisks display as-is **
Markdown supports backslash escaping for the following characters:
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash
+ plus sign
- minus sign
. period
! exclamation mark
2
3
4
5
6
7
8
9
10
11
12
*** The following sections are not yet supported in GitHub or other online previews ***
# Math Formulas
When you need to insert math formulas in the editor, use two dollar signs $$ to wrap TeX or LaTeX formatted math formulas. After submission, Q&A and article pages will load Mathjax as needed to render the math formulas. For example:
$$
\mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix}
\mathbf{i} & \mathbf{j} & \mathbf{k} \\
\frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\
\frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \\
\end{vmatrix}
$$tep1}{\style{visibility:hidden}{(x+1)(x+1)}}
$$
2
3
4
5
6
7
8
$$ \mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix} \mathbf{i} & \mathbf{j} & \mathbf{k} \ \frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \ \frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \ \end{vmatrix} $$
# Charts
```chart
,Budget,Income,Expenses,Debt
June,5000,8000,4000,6000
July,3000,1000,4000,3000
Aug,5000,7000,6000,3000
Sep,7000,2000,3000,1000
Oct,6000,5000,4000,2000
Nov,4000,3000,5000,
type: pie
title: Monthly Revenue
x.title: Amount
y.title: Month
y.suffix: $
```
```mermaid
sequenceDiagram
A->>B: Have you received the message?
B-->>A: Message received
```
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Note: Not supported in Typora
# Flowcharts
Syntax:
```mermaid
graph TD
A[Module A] -->|A1| B(Module B)
B --> C{Condition C}
C -->|Condition C1| D[Module D]
C -->|Condition C2| E[Module E]
C -->|Condition C3| F[Module F]
```
2
3
4
5
6
7
8
9
Related articles on flowcharts:
https://www.jianshu.com/p/b421cc723da5 (opens new window)
http://www.imooc.com/article/292708 (opens new window)
# Sequence Diagrams
```mermaid
sequenceDiagram
A->>B: Have you received the message?
B-->>A: Message received
```
2
3
4
5
# Gantt Charts
```mermaid
gantt
title Gantt Chart
dateFormat YYYY-MM-DD
section Project A
Task 1 :a1, 2018-06-06, 30d
Task 2 :after a1 , 20d
section Project B
Task 3 :2018-06-12 , 12d
Task 4 : 24d
```
2
3
4
5
6
7
8
9
10
11