什么是Markdown
<!--你可能没听说过 Markdown，也可能听说过但没有习惯用它写文档。为了这样的你！我们首先来说 Markdown 是什么，以及使用它的优点。 -->
Markdown 是一种用来写作的轻量级「标记语言」，能够帮助人们用更简单、快速的方式去编辑文章，而不需要过多的去担心排版问题
传统痛点：
- 文件格式难兼容
- 显示的效果不一致
- 功能繁杂、排版耗时等等问题
优点
- 专注你的文字内容而不是排版样式，安心写作。
- 轻松的导出 HTML、PDF 和本身的 .md 文件。
- 纯文本内容，兼容所有的文本编辑器与字处理软件。
- 随时修改你的文章版本，不必像字处理软件生成若干文件版本导致混乱。
- 可读、直观、学习成本低, 特别是长文本用Markdown标注后，结构更清晰，逻辑更明显。
- 用尽可能少字节的纯文本，带来统一美观可预测的展现
- 兼容HTML
- 天生适合与git/svn结合使用，可追溯，多人协作
- 操作方便，效率高，写作时使用鼠标较少
文档管理
Markdown 是一种纯文本格式，特别适合于Git/SVN进行版本控制
$$ 文档 == 代码 $$
<!-- 但是用 Markdown 之后，文档就和代码一样是一行行的纯文本；图片之类的资源是外链的，不改动图片本身就不会产生提交。这就大大提高了版本控制的效率。文档可以像代码一样享受版本控制的优点了。 -->
可读性
其次，Markdown 在设计时就考虑了可读性，比如下面这段 Markdown 代码：
# Sec 1
# Sec 1.1
The *quick* brown fox jumps over the **lazy** dog.我觉得对于一个没接触过 Markdown 的人来说这段话也不难理解。有一些奇怪的星号，但是不影响我们找到正文。
如果是 LaTeX 的话，要写成这样：
\documentclass{article}
\begin{document}
\section{Sec 1}
\subsection{Sec 1.1}
The \emph{quick} brown fox jumps over the {\bfseries lazy} dog.
\end{document}Markdown 的语法之所以如此简洁，一方面是因为用一些简单的符号代替了繁杂的格式描述，另一方面是因为 Markdown 本身不关心自己会被如何显示，而是将显示的工作交给了预览工具。
强大的表达能力
Markdown 在显示时会被预览工具翻译为 HTML。
比如# XXX会被翻译为<h1>XXX</h1>。
这一点非常了不起，因为：
- Markdown 是 HTML 的一种简写，在显示时会『解压缩』成 HTML。理论上你可以在 Markdown 里直接插入合法的 HTML 块，他们会成为最终的 HTML 的一部分，做到 Markdown 本身做不到的事。
- Markdown 的格式可以由 CSS 描述, 预览工具或者用户可以自己决定用什么 CSS 显示，怎么好看怎么来CSS 这个东西我们都知道，是可以怼天怼地怼空气的……
基本语法
标题语法
要创建标题，请在单词或短语前面添加井号 (#) 。# 的数量代表了标题的级别。例如，添加三个 # 表示创建一个三级标题 (<h3>) (例如：### My Header)。
| Markdown语法 | HTML | 预览效果 |
|---|---|---|
# Heading level 1 | <h1>Heading level 1</h1> | <h1> Heading level 1</h1> |
## Heading level 2 | <h2>Heading level 2</h2> | <h2>Heading level 2</h2> |
### Heading level 3 | <h3>Heading level 3</h3> | <h3>Heading level 3</h3> |
#### Heading level 4 | <h4>Heading level 4</h4> | <h4>Heading level 4</h4> |
##### Heading level 5 | <h5>Heading level 5</h5> | <h5>Heading level 5</h5> |
###### Heading level 6 | <h6>Heading level 6</h6> | <h6>Heading level 6</h6> |
Attention: #与文本之间留一个空格
| Do this | Don't do this |
|---|---|
# Here's a Heading | #Here's a Heading |
强调语法
通过将文本设置为粗体或斜体来强调其重要性。
| Markdown语法 | HTML | 预览效果 |
|---|---|---|
I just love **bold text**. | I just love <strong>bold text</strong>. | I just love bold text. |
Italicized text is the *cat's meow*. | Italicized text is the <em>cat's meow</em>. | Italicized text is the cat's meow. |
This text is ***really important***. | This text is <strong><em>really important</em></strong>. | This text is really important. |
引用语法
要创建引用，在段落前添加>符号, 嵌套引用的话，在要嵌套的段落前加>>
下面文字：
> This is one quota.
>
>> This is the embded quota.渲染效果如下：
This is one quota.
This is the embded quota.
某些Markdown格式可以在引用块中使用， 这个和具体的渲染器相关，要自己实验哪此可以使用。
> #### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going according to **plan**.渲染效果如下：
The quarterly results look great!
- Revenue was off the chart.
Profits were higher than ever.
Everything is going according to plan.
列表
有序列表
要创建有序列表，请在每个列表项前添加数字并紧跟一个英文句点。数字不必按数学顺序排列，但是列表应当以数字 1 起始。
| Markdown语法 | HTML | 预览效果 |
|---|---|---|
| 1. First item 2. Second item 3. Third item 4. Fourth item | <ol> <li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ol> | 1. First item 2. Second item 3. Third item 4. Fourth item |
| 1. First item 2. Second item 3. Third item 1. Indented item 2. Indented item 4. Fourth item | <ol><li>First item</li><li>Second item</li><li>Third item<ol><li>Indented item</li><li>Indented item</li></ol></li><li>Fourth item</li></ol> | <ol><li>First item</li><li>Second item</li><li>Third item<ol><li>Indented item</li><li>Indented item</li></ol></li><li>Fourth item</li></ol> |
无序列表
要创建无序列表，请在每个列表项前面添加破折号 (-)、星号 (*) 或加号 (+) 。缩进一个或多个列表项可创建嵌套列表。
| Markdown语法 | HTML | 预览效果 |
|---|---|---|
| - First item - Second item - Third item - Fourth item | <ul> <li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ul> | <ul> <li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ul> |
| - First item - Second item - Third item - Indented item - Indented item - Fourth item | <ol><li>First item</li><li>Second item</li><li>Third item<ol><li>Indented item</li><li>Indented item</li></ol></li><li>Fourth item</li></ol> | <ul><li>First item</li><li>Second item</li><li>Third item<ul><li>Indented item</li><li>Indented item</li></ul></li><li>Fourth item</li></ul> |
Attention 不要滥用+, *, -
在列表中嵌套其他元素
要在保留列表连续性的同时在列表中添加另一种元素，请将该元素缩进四个空格或一个制表符
举例-在列表项目中保留段落
* This is the first list item.
* Here's the second list item.
I need to add another paragraph below the second list item.
* And here's the third list item.渲染效果如下：
- This is the first list item.
Here's the second list item.
I need to add another paragraph below the second list item.
- And here's the third list item.
举例-在列表中保留引用
* This is the first list item.
* Here's the second list item.
> A blockquote would look great below the second list item.
* And here's the third list item.渲染效果如下：
- This is the first list item.
Here's the second list item.
A blockquote would look great below the second list item.
- And here's the third list item.
举例-在列表中保留代码表
代码块通常采用四个空格或一个制表符缩进。当它们被放在列表中时，请将它们缩进八个空格或两个制表符
1. Open the file.
2. Find the following code block on line 21:<html>
<head>
<title>Test</title>
</head>
```Update the title to match the name of your website.
渲染效果如下：- Open the file.
Find the following code block on line 21:
<html> <head> <title>Test</title> </head>Update the title to match the name of your website.
举例-在列表中使用图片
- Open the file containing the Linux mascot.
- Marvel at its beauty.
Close the file.
渲染效果如下：- Open the file containing the Linux mascot.
- Marvel at its beauty.
Close the file.
代码语法
- 如果要将单词或短语表示为代码，直接将其包裹在反引号(`)中
如果要用一段代码表示为代码，用
`将代码包裹好，并可以加上语言类型如下代码
```verilog module test();
reg clk=0;
reg [31:0] cnt = 0;
always @(posedge clk) begin
cnt <= cnt + 1;
end
endmodule
````
渲染效果
module test();
reg clk=0;
reg [31:0] cnt = 0;
always @(posedge clk) begin
cnt <= cnt + 1;
end
endmodule
# 分隔线
要创建分隔线，请在单独一行上使用三个或多个星号 (***)、破折号 (---) 或下划线 (___) ，并且不能包含其他内容。
first paragraph
second paragraph
效果如下
first paragraph
---
second paragraph
# 链接
超链接Markdown语法代码：`[超链接显示名](超链接地址 "超链接title")`
对应的HTML代码为： `<a href="超链接地址" title="超链接title">超链接显示名</a>`
超链接title是可选项。
这是一个链接 Markdown语法
渲染效果如下：
这是一个链接 [ETMCU](https://wiki.etmcu.com "最好的MCU供应商")
## 网址和Email
使用尖括号可以很方便地把URL或者email地址变成可点击的链接。
比如:https://markdown.com.cn
mailto:fake@etmcu.com
渲染效果如下：
<https://markdown.com.cn>
<fake@etmcu.com>
## 带格式的链接
强调 链接, 在链接语法前后增加星号。 要将链接表示为代码，请在方括号中添加反引号。
I love supporting the EFF.
This is the Markdown Guide.
See the section on code.
渲染效果如下：
I love supporting the **[EFF](https://eff.org)**.
This is the *[Markdown Guide](https://www.markdownguide.org)*.
See the section on [`code`](https://sf.gg).
## 引用类型链接
实际用例如下：
- [IT Guide][1]
- [Vim][2]
# 图像
要添加图像，请使用感叹号 (!), 然后在方括号增加替代文本，图片链接放在圆括号里，括号里的链接后可以增加一个可选的图片标题文本。
插入图片Markdown语法代码：``。
对应的HTML代码：`<img src="图片链接" alt="图片alt" title="图片title">`
如下代码
渲染效果如下：
# 任务列表
- [x] @mentions, #refs, [links](), formatting, and
tagssupported - [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
[ ] this is an incomplete item
渲染效果如下:- [x] @mentions, #refs, [links](), formatting, and
tagssupported - [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
[ ] this is an incomplete item
转义字符
要显示原本用于格式化 Markdown 文档的字符，请在字符前面添加反斜杠字符 \ 。
Character Name \ backslash \` backtick (see also escaping backticks in code) * asterisk \_ underscore { } curly braces [ ] brackets ( ) parentheses \# pound sign + plus sign - minus sign (hyphen) . dot \! exclamation mark \ pipe (see also escaping pipe in tables) 在 HTML 文件中，有两个字符需要特殊处理：
<和&。<符号用于起始标签，&符号则用于标记 HTML 实体，如果你只是想要使用这些符号，你必须要使用实体的形式，像是<和&。内嵌HTML标签
markdown支持直接使用HTML标签，但不建议直接使用
MPE 扩展
上下标
用法 语法 效果 上标 30^th^30^th^ 下标 H~2~OH~2~O 脚注
Content 1
LateX
你可以查看 KaTeX supported functions/symbols 来了解 KaTeX 支持那些符号和函数。
下面是一个例子
$$\begin{aligned} f(x) = sin(x) + 12 \\ y = \sum_{n=1}^{100} n \end{aligned}$$渲染效果如下：
$$ \begin{aligned} f(x) = sin(x) + 12 \\ y = \sum_{n=1}^{100} n \end{aligned} $$
wavedrom
timing
```wavedrom { signal: [ { name: "CK", wave: "P.......", period: 2 }, { name: "CMD", wave: "x.3x=x4x=x=x=x=x", data: "RAS NOP CAS NOP NOP NOP NOP", phase: 0.5 }, { name: "ADDR", wave: "x.=x..=x........", data: "ROW COL", phase: 0.5 }, { name: "DQS", wave: "z.......0.1010z." }, { name: "DQ", wave: "z.........5555z.", data: "D0 D1 D2 D3" } ]} ```{ signal: [ { name: "CK", wave: "P.......", period: 2 }, { name: "CMD", wave: "x.3x=x4x=x=x=x=x", data: "RAS NOP CAS NOP NOP NOP NOP", phase: 0.5 }, { name: "ADDR", wave: "x.=x..=x........", data: "ROW COL", phase: 0.5 }, { name: "DQS", wave: "z.......0.1010z." }, { name: "DQ", wave: "z.........5555z.", data: "D0 D1 D2 D3" } ]}bitfield
```wavedrom {reg: [ {bits: 2, name: 'End', attr: ['0x7F'], type: 5}, {bits: 4, name: 'CRC', attr: ['CRC16', 'x1041','Bits 13:6'], type: 2}, {bits: 2, name: 'Ctrl', attr: ['ON = x01', 'OFF = x00'], type: 4}, {bits: 2, name: 'Size', attr: 'x01', type: 4}, {bits: 2, name: 'Cmd', attr: 'xAA', type: 4}, {bits: 2, name: 'Req/Reply', attr: ['Req x01', 'Rep x00'], type: 4}, {bits: 12, name: 'Head', attr: ['xEB x90 xEB x90 xEB x90'], type: 5}, ], config:{bits: 26} } ```{reg: [ {bits: 2, name: 'End', attr: ['0x7F'], type: 5}, {bits: 4, name: 'CRC', attr: ['CRC16', 'x1041','Bits 13:6'], type: 2}, {bits: 2, name: 'Ctrl', attr: ['ON = x01', 'OFF = x00'], type: 4}, {bits: 2, name: 'Size', attr: 'x01', type: 4}, {bits: 2, name: 'Cmd', attr: 'xAA', type: 4}, {bits: 2, name: 'Req/Reply', attr: ['Req x01', 'Rep x00'], type: 4}, {bits: 12, name: 'Head', attr: ['xEB x90 xEB x90 xEB x90'], type: 5}, ], config:{bits: 26} }mermiad
mermaid支持
- Flowchart
- Sequence Diagram
- Class Diagram
- State Diagram
- Entity Relationship Diagram
- User Journey
- Gantt
- Pie Chart
- Requirement Diagram
GitGraph Diagram
Here are some examples.
Flowchart
```mermaid graph TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[fa:fa-car Car] ```效果如下：
Sequence Diagram
```mermaid sequenceDiagram participant Alice participant Bob Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts <br/>prevail! John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good! ```效果如下：
State Diagram
```mermaid stateDiagram-v2 [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*] ```效果如下：
Pie Chart
```mermaid pie title Pets adopted by volunteers "Dogs" : 386 "Cats" : 85 "Rats" : 15 ```效果如下：
Class Diagram
```mermaid classDiagram Animal <|-- Duck Animal <|-- Fish Animal <|-- Zebra Animal : +int age Animal : +String gender Animal: +isMammal() Animal: +mate() class Duck{ +String beakColor +swim() +quack() } class Fish{ -int sizeInFeet -canEat() } class Zebra{ +bool is_wild +run() } ```效果如下：
Gantt Diagram
```mermaid gantt dateFormat YYYY-MM-DD title Adding GANTT diagram to mermaid excludes weekdays 2014-01-10 section A section Completed task :done, des1, 2014-01-06,2014-01-08 Active task :active, des2, 2014-01-09, 3d Future task : des3, after des2, 5d Future task2 : des4, after des3, 5d ```效果如下：
ditta
简单说明
cXXX： XXX分别代表RGB的比例
也可以直接用颜色名称, 如：cRED,cGRE,cBLK,cYEL,cBLU,cPNK```ditaa {cmd=true args=["-E"] hide=true} +---------------------+ | c1FF | | SKY | +---------------------+ | | | cGRE | | | | | | PLAY | | GROUND | | | | | | | | | | | |/-\/-\/-\/-\ | |\-/\-/\-/\-/ | +---------------------+ ```效果如下
+---------------------+ | c1FF | | SKY | +---------------------+ | | | cGRE | | | | | | PLAY | | GROUND | | | | | | | | | | | |/-\/-\/-\/-\ | |\-/\-/\-/\-/ | +---------------------+PlantUML
```plantuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response Alice -> Bob: Another authentication Request Alice <-- Bob: Another authentication Response ```效果如下：
Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response Alice -> Bob: Another authentication Request Alice <-- Bob: Another authentication Responsevega
柱状图
```vega-lite { "$schema": "https://vega.github.io/schema/vega-lite/v5.json", "description": "A simple bar chart with embedded data.", "renderer": "png", "width": 600, "height": 480, "padding": 5, "data": { "values": [ {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43}, {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53}, {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52} ] }, "mark": "bar", "encoding": { "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}}, "y": {"field": "b", "type": "quantitative"} } } ```效果如下：
{ "$schema": "https://vega.github.io/schema/vega-lite/v5.json", "description": "A simple bar chart with embedded data.", "renderer": "canvas", "width": 600, "height": 480, "padding": 5, "data": { "values": [ {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43}, {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53}, {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52} ] }, "mark": "bar", "encoding": { "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}}, "y": {"field": "b", "type": "quantitative"} } }高级柱状图
```vega { "$schema": "https://vega.github.io/schema/vega/v5.json", "description": "A basic grouped bar chart example.", "width": 600, "height": 480, "padding": 5, "data": [ { "name": "table", "values": [ {"category":"A", "position":0, "value":0.1}, {"category":"A", "position":1, "value":0.6}, {"category":"A", "position":2, "value":0.9}, {"category":"A", "position":3, "value":0.4}, {"category":"B", "position":0, "value":0.7}, {"category":"B", "position":1, "value":0.2}, {"category":"B", "position":2, "value":1.1}, {"category":"B", "position":3, "value":0.8}, {"category":"C", "position":0, "value":0.6}, {"category":"C", "position":1, "value":0.1}, {"category":"C", "position":2, "value":0.2}, {"category":"C", "position":3, "value":0.7} ] } ], "scales": [ { "name": "yscale", "type": "band", "domain": {"data": "table", "field": "category"}, "range": "height", "padding": 0.2 }, { "name": "xscale", "type": "linear", "domain": {"data": "table", "field": "value"}, "range": "width", "round": true, "zero": true, "nice": true }, { "name": "color", "type": "ordinal", "domain": {"data": "table", "field": "position"}, "range": {"scheme": "category20"} } ], "axes": [ {"orient": "left", "scale": "yscale", "tickSize": 0, "labelPadding": 4, "zindex": 1}, {"orient": "bottom", "scale": "xscale"} ], "marks": [ { "type": "group", "from": { "facet": { "data": "table", "name": "facet", "groupby": "category" } }, "encode": { "enter": { "y": {"scale": "yscale", "field": "category"} } }, "signals": [ {"name": "height", "update": "bandwidth('yscale')"} ], "scales": [ { "name": "pos", "type": "band", "range": "height", "domain": {"data": "facet", "field": "position"} } ], "marks": [ { "name": "bars", "from": {"data": "facet"}, "type": "rect", "encode": { "enter": { "y": {"scale": "pos", "field": "position"}, "height": {"scale": "pos", "band": 1}, "x": {"scale": "xscale", "field": "value"}, "x2": {"scale": "xscale", "value": 0}, "fill": {"scale": "color", "field": "position"} } } }, { "type": "text", "from": {"data": "bars"}, "encode": { "enter": { "x": {"field": "x2", "offset": -5}, "y": {"field": "y", "offset": {"field": "height", "mult": 0.5}}, "fill": [ {"test": "contrast('white', datum.fill) > contrast('black', datum.fill)", "value": "white"}, {"value": "black"} ], "align": {"value": "right"}, "baseline": {"value": "middle"}, "text": {"field": "datum.value"} } } } ] } ] } ```效果如下:
{ "$schema": "https://vega.github.io/schema/vega/v5.json", "description": "A basic grouped bar chart example.", "width": 600, "height": 480, "padding": 5, "data": [ { "name": "table", "values": [ {"category":"A", "position":0, "value":0.1}, {"category":"A", "position":1, "value":0.6}, {"category":"A", "position":2, "value":0.9}, {"category":"A", "position":3, "value":0.4}, {"category":"B", "position":0, "value":0.7}, {"category":"B", "position":1, "value":0.2}, {"category":"B", "position":2, "value":1.1}, {"category":"B", "position":3, "value":0.8}, {"category":"C", "position":0, "value":0.6}, {"category":"C", "position":1, "value":0.1}, {"category":"C", "position":2, "value":0.2}, {"category":"C", "position":3, "value":0.7} ] } ], "scales": [ { "name": "yscale", "type": "band", "domain": {"data": "table", "field": "category"}, "range": "height", "padding": 0.2 }, { "name": "xscale", "type": "linear", "domain": {"data": "table", "field": "value"}, "range": "width", "round": true, "zero": true, "nice": true }, { "name": "color", "type": "ordinal", "domain": {"data": "table", "field": "position"}, "range": {"scheme": "category20"} } ], "axes": [ {"orient": "left", "scale": "yscale", "tickSize": 0, "labelPadding": 4, "zindex": 1}, {"orient": "bottom", "scale": "xscale"} ], "marks": [ { "type": "group", "from": { "facet": { "data": "table", "name": "facet", "groupby": "category" } }, "encode": { "enter": { "y": {"scale": "yscale", "field": "category"} } }, "signals": [ {"name": "height", "update": "bandwidth('yscale')"} ], "scales": [ { "name": "pos", "type": "band", "range": "height", "domain": {"data": "facet", "field": "position"} } ], "marks": [ { "name": "bars", "from": {"data": "facet"}, "type": "rect", "encode": { "enter": { "y": {"scale": "pos", "field": "position"}, "height": {"scale": "pos", "band": 1}, "x": {"scale": "xscale", "field": "value"}, "x2": {"scale": "xscale", "value": 0}, "fill": {"scale": "color", "field": "position"} } } }, { "type": "text", "from": {"data": "bars"}, "encode": { "enter": { "x": {"field": "x2", "offset": -5}, "y": {"field": "y", "offset": {"field": "height", "mult": 0.5}}, "fill": [ {"test": "contrast('white', datum.fill) > contrast('black', datum.fill)", "value": "white"}, {"value": "black"} ], "align": {"value": "right"}, "baseline": {"value": "middle"}, "text": {"field": "datum.value"} } } } ] } ]
## 参考学习资料
- [Markdown中国](https://markdown.com.cn/)
- [PlantUML](https://plantuml.com/zh/)
- [mermiad](https://mermaid-js.github.io/mermaid/#)
- [wavedrom](https://github.com/wavedrom/schema/blob/master/WaveJSON.md)
- [bitfield](https://github.com/wavedrom/bitfield)
[1]: http://wiki.etmcu.com/zh/info/general_guide
[2]: http://wiki.etmcu.com/zh/training/tools/vim/tutorial
- 1 ↩
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。