• 帮助文档

# Markdown 简单介绍

Markdown 语法是轻量级文本标记语言。Markdown 语法因为简单易学、功能强大， 而且 Markdown 格式也可以转换成 html, pdf 等。所以也是很多程序员都非常喜欢的一种语言。

下面我就来介绍些 Markdown 的一些常用功能：

# 1. 目录

- [目录](#_1-目录)
- [快速生成目录大纲](#_2-快速生成目录大纲)
- [标题](#_3-标题)
- [强调样式](#_4-强调样式)
- [列表](#_5-列表)
- [分隔线](#_6-分隔线)
- [表格](#_7-表格)
- [任务列表](#_8-任务列表)
- [项目引用操作](#_9-项目引用操作)
- [区块引用](#_10-区块引用)
- [代码框](#_11-代码框)
- [插入图片](#_12-插入图片)
- [插入链接](#_13-插入链接)
- [插入表情符号](#_14-插入表情符号)
- [插入 Latex 数学公式](#_15-插入-latex-数学公式)
- [宏](#_16-宏)
- [使用 mermaid 绘制图表](#_17-使用-mermaid-绘制图表)
- [Front Matter](#_18-front-matter)

# 2. 快速生成目录大纲

在文档最前面加上 [TOC] ，Markdown 编辑器就会把文章中所有标题都写到目录大纲中。

# 3. 标题

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

##### 五级标题

###### 六级标题

# 4. 强调样式

*斜体* 或者 _斜体_

**加粗** 或者 __加粗__

***斜体并加粗*** 或者 **_斜体并加粗_** 或者 __*斜体并加粗*__

~~删除线~~

`行内代码`

斜体 或者 斜体

加粗 或者 加粗 斜体并加粗 或者 斜体并加粗 或者 斜体并加粗

删除线

行内代码

# 5. 列表

# 5.1 有序列表
1. 有序列表只需在文字前加 一个数字和一个英文句点
2. 数字不管有序还是无序
3. 结果都是有序的

1995\. 如果要在行首输入数字，在数字后面加上反斜杠转义点符号即可。
  1. 有序列表只需在文字前加 一个数字和一个英文句点
  2. 数字不管有序还是无序
  3. 结果都是有序的

1995. 如果要在行首输入数字，在数字后面加上反斜杠转义点符号即可。

# 5.2 无序列表

有三个符号表示无序列表 * + -

- 无序列表

* 无序列表

- 符号和文字之间要加空格
  • 无序列表
  • 无序列表
  • 符号和文字之间要加空格

# 6. 分隔线

在一行用三个以上的 * 或者 - 或者 _ 即可新建一条分隔线。

万恶的分隔线

---

吼吼吼

万恶的分隔线

吼吼吼

# 7. 表格

语法说明：

  1. 第一行为表头，第二行是单元格对齐控制行，用来控制对应列单元格的文字对齐方式，第三行开始为表格内容；
  2. 第二行中输入:可对齐该列的内容。详情见下
| 左对齐         |    居中对齐    |         右对齐 |
| :------------- | :------------: | -------------: |
| 今天天气怎么样 | 今天天气怎么样 | 今天天气怎么样 |
| 有点热         |     有点热     |         有点热 |
左对齐 居中对齐 右对齐
今天天气怎么样 今天天气怎么样 今天天气怎么样
有点热 有点热 有点热

# 8. 任务列表

在项目的缺陷、合并请求和描述中可添加任务列表。

- [x] 表示已经完成的任务
- [ ] 表示正在进行的任务
  - [x] files-test 1
  - [ ] files-test 2
  - [ ] files-test 3

# 9. 项目引用操作

在项目操作中，引用这个功能也是十分方便的。

# 9.1 项目内引用
输入 引用
@user_name @用户
@group_name @组
@all @整个团
#1 缺陷
!1 合并请求
~1 标签 ID
~bug 一个词的标签名字
~"feature request" 多词标签名字
efada38f 具体提交
efada28f...afbe4ff6 提交范围比较
[README](doc/README) 库文件引用
# 9.2 跨项目引用
输入 引用
namespace/project#1 缺陷
namespace/project!1 合并请求
namespace/project@efada38f 具体提交
namespace/project@efada38f...afbe4ff6 提交范围比较

# 10. 区块引用

> Markdown 的区块引用类似 email 中`> ` 的引用方式。
>
> > 嵌套的引用也是支持的哦。
>
> 要注意的是`>`后面是有一个空格的。

Markdown 的区块引用类似 email 中> 的引用方式。

嵌套的引用也是支持的哦。 要注意的是>后面是有一个空格的。

# 11. 代码区块

用连续三个反引号 ``` 作为起始行，并以连续三个反引号作为结束行，将代码区块包裹起来。

或者在行首使用四个空格缩进，也可以将文本转换为代码区块。

使用反引号风格的代码区块，可以在起始行后写入语言名称实现代码高亮。缩进风格的代码区块不支持代码高亮。

```javascript
var s = "Hello world";
alert(s);
```
```css
span.highlight{
    background-color:yellow
}
```

var s = "Hello world";
alert(s);

span.highlight {
  background-color: yellow;
}

# 12. 插入图片

图片的语法为 ![]()

内联式：
![a](images/logo/touch-icon-ipad.png)

引用式：
![a][logo]

[logo]: images/logo/touch-icon-ipad.png

内联式:

a

引用式:

a

# 13. 插入链接

链接的语法与图片的语法非常相似，只是差了一个 !

链接的语法为 []()

[内联样式](https://www.tencent.com)

[引用样式][引用的文本不区分大小写]

[对项目中文件的相对引用](/Code_Review/Review/blob/master/readme.md)

[您可以使用数字作为引用样式的定义链接][22]

或者不输入内容然后使用 [文件本身链接]

参考的链接可以放在要显示的文本后面。

[引用的文本不区分大小写]: https://www.tencent.com
[22]: https://baike.sogou.com
[文件本身链接]: https://www.baidu.com

内联样式

引用样式

对项目中文件的相对引用

您可以使用数字作为引用样式的定义链接

或者不输入内容然后使用 文件本身链接

引用的链接放在要显示的文本后面。

注意

相对链接不允许引用 wiki 页中的项目文件或项目文件中的 wiki 页。因为在 工蜂 Git 中，wiki 始终是一个单独的工蜂 Git 仓库。

# 14. 插入表情符号

在 Markdown 中，还有一个特别有意思的功能，就是可以插入表情符号😄

有时候如果您想在文本中加入一些 :hibiscus: 、 :rabbit2: ，或者是 :eyeglasses: 。那怎么办呢？

哈哈，别着急，其实在 Markdown 中使用表情 :grin: 是件很简单的事；

:dizzy: 如果您不知道哪些代码代表哪些表情 :hushed: ，那您可以去[表情符号大全](https://emoji.codes)获取所有支持的表情符号代码列表。

比如你可以使用 :bug: 来指出一个 bug 或者是用 :monkey_face: 来表示一个警告补丁。

如果工作中有同事帮助了你，你可以用一个 :smile: 表示你很开心。

有时候如果您想在文本中加入一些 🌺 、 🐇 ，或者是 👓 。那怎么办呢？

哈哈，别着急，其实在 Markdown 中使用表情 😁 是件很简单的事；

💫 如果您不知道哪些代码代表哪些表情 😯 ，那您可以去表情符号大全获取所有支持的表情符号代码列表。

比如你可以使用 🐛 来指出一个 bug 或者是用 🐵 来表示一个警告补丁。

如果工作中有同事帮助了你，你可以用一个 😄 表示你很开心。

# 15. 插入 Latex 数学公式

关于数学公式语法：

工蜂默认兼容 GitLab 风格的数学公式语法，如需使用 Typora、GitHub 等平台的语法。 可参考 Front Matter - 配置数学公式风格 进行配置。

工蜂使用KaTeX来渲染数学公式.

语法：

行内公式： $`xxxxx`$.
行间公式：
```math
xxxx
xxxx
```

例子：

这种公式会嵌入文本 $`a^2+b^2=c^2`$.

这种公式会渲染成单独的一行
```math
a^2+b^2=c^2
```

markdown_formula

# 16. 宏

工蜂支持简单的宏，通过宏定义和宏引用能够在普通文本中包含一些复杂的 markdown 元素。

宏定义

宏定义以>>> macro1(宏的名称) 的一行开头，其中宏名称由 a-z，A-Z，0-9， - 或_组成，并由带有<<<的行终止。这些行之间的文本都会以 markdown 进行解析。宏定义不会直接输出

宏引用

引用宏的语法为：<<< macro1(之前定义的宏名称) >>>，在 markdown 渲染时<<< macro1(之前定义的宏名称) >>>将被对应的宏定义中的内容替换，如果定义多个相同名称的宏则以第一个为准

例子:

在段落中插入文本 <<<macro1>>>.

>>>macro1
simple text
<<<


在段落中插入列表 <<<macro2>>>

>>>macro2
1. item 1
1. item 2
<<<

大招：在列表里面使用宏


| 说明 | 请求 | 相应 |
| ------- |---- | ------ |
| 获取 xxx | <<<request>>> | <<<response>>> |


>>>request
```
{
"key1": "xxx",
"key2": "xxx"
}
```
<<<

>>>response
```
{
"key1": "xxx",
"key2": [
         "xxx",
         "zzz"
        ]
}
```
<<<

markdown_macros

# 17. 使用 mermaid 绘制图表

工蜂 Git 支持使用mermaid-js语法进行流程图、时序图、类图等图表的绘制。

在代码区块的语言名称处填入mermaid，区块中所有的内容都会交由mermaid进行图表绘制。

以下仅展示部分图表的绘制示例，详细的绘图语法请参考mermaid 官网。

语法示例：

饼图(Pie Chart)

```mermaid
pie title What Voldemort doesn't have?
     "FRIENDS" : 2
     "FAMILY" : 3
     "NOSE" : 45
```

mermaid-pie

时序图(Sequence Diagram)

```mermaid
sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?
```

mermaid-seq

流程图(Flowchart)

```mermaid
graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
```

mermaid-flowchart

类图(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()
    }
```

mermaid-class-diag

状态图(State Diagram)

```mermaid
stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

mermaid-state-diag

实体关系图(ER Diagram)

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

mermaid-er-diag

甘特图(Gantt)

```mermaid
gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    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

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h
```

mermaid-gantt

# 18. Front Matter

工蜂支持渲染 Yaml 格式的 Front Matter。Front Matter 必须附加在 markdown 文档的开头，Yaml 内容使用三个 - 开头和三个 - 结尾包裹。

Front Matter 中仅支持有限的 Yaml 语法。

---
# 简单的属性
title: foo
author: bar
# 重复的 key 以最后一个为主
author: bar2
# 简单的数组
items:
  - a
  - b
  - c
---
yaml_front_matter

进阶用法： 使用 Yaml Front Matter 配置部分渲染行为

# 18.1 math_style 配置数学公式渲染风格

工蜂默认兼容 GitLab 风格的数学公式渲染，如需使用 Typora、GitHub 等平台风格的数学公式，可以通过配置 math_style 实现。可选的值包括：gitlab (默认值)、generic。

---
# 通用风格的数学公式语法
# 行内数学公式 $e=mc^2$
# 多行数学公式
# $$
# e=mc^2
# $$
math_style: generic
---
行内数学公式 $e=mc^2$
多行数学公式
$$
e=mc^2
$$
front_matter__math_style

不配置或配置为 gitlab 时，使用 GitLab 风格的数学公式语法

---
# GitLab 风格的数学公式语法
# 行内数学公式 $`e=mc^2`$
# 多行数学公式
# ```math
# e=mc^2
# ```
math_style: gitlab
---
行内数学公式 $`e=mc^2`$
多行数学公式
```math
e=mc^2
```
# 18.2 hide_frontmatter 隐藏 Front Matter 表格

工蜂可以通过配置 hide_frontmatter 隐藏 Front Matter 表格。

---
hide_frontmatter: true
math_style: generic
---

隐藏 front_matter，同时使用通用风格的行内数学公式 $e=mc^2$。

使用通用风格的多行数学公式：

$$
e=mc^2
$$
yaml_frontmatter__hide
lastUpdate: 7/21/2023, 5:06:11 PM

← 网页快捷键 →