目录
在Git上创建一个项目时基本都会提示创建一个README.md文件，比如使用GitLab创建一个项目时，在项目下面有如下命令提示：
git clone git@my_git_hostname:root/项目名.git
cd test
touch README.md
git add README.md
git commit -m "add README"
其中创建的README.md文件就是一个Markdown的文件，Wiki文档的编写也可以使用Markdown语法编写。在这个文件中想写出条例清晰、结构美观的文档，需要了解基本的Markdown语法，而且好的README.md可以让这个项目更好的被其他人理解和查看。在GitHub上的开源的顶级项目的文档一般写的都很棒，所以对使用者或者开发者就很友好，可以多在GitHub上看下Apache顶级项目的文档，自己也尽量在项目中尝试写好README.md文档。
1. 题目
一个md文件或者其中完整的一部分内容可以加上一个题目，当然这个也可以使用一级标题或者二级标题，例如创建了”GraphX项目标题“可以如下定义：
GraphX Programming Guide
=
GraphX Programming Guide
-
=相比于-显示的效果要大一些，并且输入1个或者多个都可以，=类似于一级标题，-类似于二级标题，在GitHub上显示效果也是和一级标题和二级标题差不多，如下(有些编辑器显示的效果可能不同，这里以GitHub上为参考)：
2. 标题
标题和HTML的标题标签差不多，也是共有6个不同级别的标题（对应于H1 ~ H6标签），在想要设定为标题的文字前加上#号就可以，一个#为一级标题，##为二级标题，以此类推，最小支持到######为六级标题。
注意： #后面一定跟一个空格，然后再写标题文字，否则没效果(有些编辑器可能没这么严格)。
# 一级标题 H1
## 二级标题 H2
### 三级标题 H3
#### 四级标题 H4
##### 五级标题 H5
###### 六级标题 H6
效果如下（一下下展示的效果是GitHub上的效果）：
3. 文字
文字的常用效果有加粗、倾斜、删除、填充、框选，用*号或者_号都可以，两种效果显示的一样。突出显示可以用反单引号。删除线不经常用到。基本这些够用了，其他关于设置字体颜色的、给文字填充其他颜色的、给某些文字加上下划线的特效的，你们可以找下其他资料，虽然Markdown支持一些常用的HTML标签，但有时编辑器就会直接忽视掉，这里说下常用，本来Markdown的初衷就应该是通过一些简单的符号快速布局一篇文章，从而专心于写作而不是布局。
*倾斜的文字*
_倾斜的文字_
**加粗的文字**
__加粗的文字__
***斜体加粗的文字***
___斜体加粗的文字___
~~这是加删除线的文字~~
我是一行文字中`突出`显示的文字
我是<kbd>框中</kbd>的文字
GitHub上显示的效果如下：
文字中还可以插入表情，使用双冒号 :表情符号码:，表情符号备忘单可访问https://www.emojicopy.com查看 Emoji Cheat Sheet。
例：
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:.
GitHub上显示的效果如下：
4. 段落
在Markdown中有时输入换行是没有任何效果的(比如在列表时有些编辑器就不识别)，我们输入的文字不管是否有换行符在没有特殊符号时都认为是一段，如果想换行除了开头用<p>表示外，可以空一行或者在上一段最后一行连输两个空格就行，这两种方式显示效果稍微有差别，加<p>和空一行的效果是一样的。
例如：
GraphX is a new component in Spark for graphs and graph-parallel computation.(后面跟两个空格)
At a high level, GraphX extends the Spark RDD by introducing a new Graph abstraction:
a directed multigraph with properties attached to each vertex and edge.
***
GraphX is a new component in Spark for graphs and graph-parallel computation.
At a high level, GraphX extends the Spark RDD by introducing a new Graph abstraction:
a directed multigraph with properties attached to each vertex and edge.
效果如下
5. 链接和图片
连接有两种形式，一种是图片连接显示，一种是超链接，基本语法为[超链接名](超链接地址 "超链接title")，链接中的双引号Title可以写也可以不写，显示图片时前面加上!即可。中括号中填写显示的内容(如果是显示图片时表示图片无法显示时替换显示的文字)，括号中写连接或者资源的路径
[Flink 官网](https://flink.apache.org/ "Apache Flink")
GitHub上展示的效果如下：
5.1 锚点
Markdown没有特定的锚点语法，不同的Markdow支持的也不相同
5.1.1 GitHub方式
GitHub自动会对标题（带#的）生成连接，锚点可以用这个连接做锚点，
- 标题中到空格的，连接中自动替换为
- - 标题中带
.的，连接中自动去除了 - 标题中带有
、的，链接中自定去除 - 如果标题中有相同的，部分标题级别，只要相同，会自动从下一个标题开始从1开始编号最后追加上
-编号
5.1.2 通用方式
可以通过组合的方式实现，Markdown的超链接语法为[连接名](连接地址)，HTML的语法为<a id="id选择" href="连接地址"> 连接名</a>
- 首先通过
a标签标记一个锚点，因为我们要使用标签的id来进行标识，也可以使用name但这个有些支持不太好(例如CSDN的Markdown编辑器)，使用id来标记一个锚点，例如创建如下锚点：<a id="operator-lifecycle-in-a-nutshell">Operator Lifecycle in a nutshell</a> - 最后就是使用这个锚点，比如在当前页面的索引目录中或者文中，需要有个链接直接跳转到上面锚点处，可以如下方式
[Operator Lifecycle in a nutshell](#operator-lifecycle-in-a-nutshell)
或者继续使用a标签：
<a href="#operator-lifecycle-in-a-nutshell">Operator Lifecycle in a nutshell</a>
6. 列表
列表一般用在写文档的目录结构时，或者在分条叙述时，除了标题可以让文档更有结构层次感外，列表也能有这个效果，但标题用的太多或者太深就感觉文档结构太复杂，主次就凸显的不是很明确了，对于某个标题下的内容如果是由条理的可以用列表布局，如果是有序的可以用有序列表展示。
列表分为无序列表和有序列表。无序列表在开头加上*或者+或者-都OK，然后再结合Tab键就可以布局一个有层次的无序列表。有序列表可以使用序号加空格的形式(点后面需要输一个空格)
例如：
### 无序列表
- 概述
- 属性 Graph
* 示例属性 Graph
- Graph 运算符
* 运算符的汇总表
* 领域聚合
+ 聚合消息 (aggregateMessages)
+ 计算级别信息
* Caching 和 Uncaching
- Pregel API
### 有序列表
1. Storm
2. Spark
3. Flink
GitHub上显示的效果如下：
*7. 引用
使用>可以控制后面段落的缩进，个数一样的>会对齐，例如：
> This is a list item with two paragraphs.
> Apache Spark™ is a unified analytics engine for large-scale data processing.
>> Apache Spark achieves high performance for both batch and streaming data,
using a state-of-the-art DAG scheduler, a query optimizer, and a physical execution engine.
GitHub预览的效果如下：
8. 表格
表格有表头和表Body，表头可以定义缩进的方式
:----:居中:----左对齐----:右对齐----默认
缩进方式有些可能支持不是很好，如下CSDN是完全支持的，但是GitHub效果看的就不是很明显了，如果没有严格要求使用默认的---- 就行，-个个数没有要求，随意，看着舒服就行 。单元格和单元格中间用|分割，|两侧可以什么字符都不加，为了美观可以加些空格或者制表符，看着美观些。
例：
region | userId | date | time
:----: | :----- | ------: | ------
ShangHai | U0010 | 2017-11-11 | 10:01:00
BeiJing | U1001 | 2017-11-11 | 10:01:00
BeiJing | U2032 | 2017-11-11 | 10:10:00
BeiJing | U1100 | 2017-11-11 | 10:11:00
ShangHai | U0011 | 2017-11-11 | 12:10:00
GitHub和CSDN上显示的效果如下：
9. 代码
单行代码可以用一对反单引号包裹起来，如：
Spark读入json文件并加载为DataFrame的语可以用 `val df = spark.read.json("logs.json")` 表示
GitHub显示的效果如下：
多行代码块使用一对三个反单引，且两边的反引号单独占一行，常用的代码基本都支持，如python、r、clojure、kotlin、java、scals、groovy、js、angularjs、xml、html、css、yaml、json、bash、sql、hql，更多标注效果可以查看网站(GitLab使用的Rouge库)http://rouge.jneen.net/。
如下面的用scala代码实现一个Spark的Graph对象：
```scala
import org.apache.spark._
import org.apache.spark.graphx._
// To make some of the examples work we will also need RDD
import org.apache.spark.rdd.RDD
// Assume the SparkContext has already been constructed
val sc: SparkContext
// Create an RDD for the vertices
val users: RDD[(VertexId, (String, String))] =
sc.parallelize(Array((3L, ("rxin", "student")), (7L, ("jgonzal", "postdoc")),
(5L, ("franklin", "prof")), (2L, ("istoica", "prof"))))
// Create an RDD for edges
val relationships: RDD[Edge[String]] =
sc.parallelize(Array(Edge(3L, 7L, "collab"), Edge(5L, 3L, "advisor"),
Edge(2L, 5L, "colleague"), Edge(5L, 7L, "pi")))
// Define a default user in case there are relationship with missing user
val defaultUser = ("John Doe", "Missing")
// Build the initial Graph
val graph = Graph(users, relationships, defaultUser)
\```
GitHub上显示的效果如下：
10. 分割线及转义字符
分割线的效果就如一级或二级标题下面显示的横线，在空行输入三个*或者-都可以，
例：
***
* * *
---
- - -
GitHub上显示的效果如下：
Markdown需要转义的字符如下，使用本身字符时需要在前面加上\
\ 反斜线
` 反引号
* 星号
_ 底线
{} 花括号
[] 方括号
() 括弧
# 井字号
+ 加号
- 减号
. 英文句点
! 惊叹号
左上：未转义的原始字符；右上：未转义时GitHub上显示的效果。
左下：转义的原始字符；右下：转义后GitHub上显示的效果。
11. 流程图
流程图可以在代码段后加上标识mermaid(美人鱼)插件来完成，但是这个支持的不是很好，遗憾的是GitHub上不支持，但是GitLab和CSDN上是可以的。更详细的可以查看 mermaid https://mermaidjs.github.io/
例：用流程图的形式表示下Storm官网首页的Topology图
```mermaid
graph TD;
Kafka-->KafkaSpout;
KafkaSpout-->Bolt11;
Bolt11-->Bolt21;
KafkaSpout-->Bolt12;
Bolt12-->Bolt21;
KafkaSpout-->Bolt13;
Bolt13-->Bolt22;
Sport2-->Bolt13;
\```
GitLab或CSDN上现实的效果如下：（左图是Storm原图，右图为用mermaid表示的Topology图）
End
