Markdown使用入门

Markdown使用入门

1. Markdown使用规范

Markdown 是一种轻量级标记语言，它既能够编写纯文本，也可以获得很好的格式化输出。为了方便阅读和团队协作，您在使用Markdown 语法时，应尽可能保持简洁并遵守统一的格式规范。如果要编写一个完整的文档，应该严格遵守如下规范，在issues等其他场合也建议遵守如下规范。

1.1 文件和文件名

• 文件名需以 .md 为后缀
• 对于全英文的文件名，建议全部小写，多个单词直接用横杠 - 连接。
• 为了醒目，某些说明文件的文件名，可以使用大写字母，比如 README 、LICENSE。
• 对于中英混合的文件名，中英文之间不要有空格或者连接符。
• 如果文件名后要加入版本号，应该用横杠 - 连接，以小写的 v 开头。
• 在 git 环境中不建议在文件名中加版本号，应该由 git 统一管理版本。
• 文件编码必须使用 UTF-8 。

下面是两个例子：

• markdown-style-guide.md
• 华为ME909s-821模块测试报告-v1.0.md

1.2. 文档布局

一个完整的文档应该遵守如下结构:

# 文档标题

简介

@[toc]
## 1. 第一章的标题

正文

### 1.1. 第一章第一节的标题

正文

1. 有序列表
2. 有序列表

正文

* 无序列表
* 无序列表

> 强调的内容 or 引用的内容

## 2. 第二章的标题

• 文档标题最好与文件名一致。
• 简介中可以加入文档说明、作者、版本信息等。
• 如果你的格式化输出工具支持[TOC]，可以用这个方式自动添加目录。
• 章节标题从二级标题##开始，最多不要超过四级。
• 章节标题前必须加入编号，必须使用数字，以点字符结尾，并跟一个空格，例如 ## 1.1. 第一章第一节的标题 。
• 章节标题下面必须插入一个空行。
• 正文的段落之间必须插入一个空行。

1.3. 文本规范

• 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格。
• 对于英文专业名词，请使用标准写法，区分大小写，例如 Wi-Fi 、 Markdown 、 HTML 等。
• 如果括号内有中文，则使用中文括号，如果括号中的内容全部是英文，则使用英文括号
• 尽量避免在一行文本内出现常规、加粗、斜体等不同样式的混排。
• 要着重强调的内容建议整段加粗，或者用 Markdown 的块引用语法> 。
• 行内插入的链接建议使用[链接文字](链接地址) 的语法。
• 行内的代码、语法关键词等必须包含在两个反引号里。
• 完整的代码段建议使用成对的三个反引号标注。
• 如果图片展示的内容只是文字、代码或者表格，请把它们转换成纯文本，不要使用图表。
• 尽量使用平台所支持的 Markdown 的扩展，例如 GitLab 的 Markdown 扩展支持表格、任务列表、流程图等：GitLab Flavored Markdown

2. Markdown语法

2.1 标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

注意：需要在符号后面加一个空格

2.2. 引用

使用标记符> 对内容进行引用：

这是一句引用

2.3. 图片 & 链接

2.3.1 图片

![图片](http://baidu.com/pic/doge.png)

2.3.2. 链接

[百度一下](http://www.baidu.com)

效果：
百度一下

2.4. 字体

2.4.1.粗体 & 斜体

1. 粗体，用4个*把内容括住，如**粗体**
   我是粗体

2. 斜体，用两个*把内容括住，如*斜体*
   我是斜体

3. 删除线，用4个~把内容括住， 如~~删除此行~~
   删除此行

4. 高亮标记, 用4个=把内容括住==高亮标记==
   高亮标记

5. 分割线, 即---,后面不能加内容

---

2.4.2 字号 & 颜色

Markdown是一种可以使用普通文本编辑器编写的标记语言，通过类似HTML的标记语法，它可以使普通文本内容具有一定的格式。但是它本身是不支持修改字体、字号与颜色等功能的！
示例：

<font face="STCAIYUN" size=5>华文彩云</font>

华文彩云

<font face="微软雅黑" size=5>微软雅黑</font>

微软雅黑

2.5. 代码框

1.5.1. 代码块

用成对的三个反引号包裹住代码, 并指定一种语言（也可以不指定）
示例如下：

int main(int argc, char **argv)
{
    printf(hello world\n);

    return 0;    
}

1.5.2 行内代码

用两个反引号将内容括住，如：

`printf(hello world\n);`

效果：
printf(hello world\n);

2.6 列表

2.6.1 有序列表

使用数字并加上 . 号来表示，如：

1. 洗手
2. 吃饭

效果：

1. 洗手
2. 吃饭

2.6.2 无序列表

示例：

* 芒果
* 香蕉
* 雪梨

效果：

• 芒果
• 香蕉
• 雪梨

2.7 脚注

在要添加注释的词语后面增加 [^1] ，文章结尾加入[^1]：空格 注释内容。
如:hello[^1] [^1]: 用于问候、接电话或引起注意
效果：
hello¹

2.7 上下标

1. 上标用法：使用双^括住内容，如：
   2^10^ = 1024

2¹⁰ = 1024

2. 下标用法：使用双~括住内容
   x~1~ + x~2~ = x~3~

x₁ + x₂ = x₃

2.8 任务

• 未完成任务
  - [ ]
• 已完成任务
  - [x]

效果：

• 扔垃圾
• 敲代码

2.9 文本对齐方式

利用 html 语法实现居中功能

• 居中
  <center>markdown居中文本</center>
  效果：

markdown居中文本

---

1. 用于问候、接电话或引起注意 ↩︎