项目中常用的Markdown语法

深藏阁楼爱情的钟 2022-02-28 03:24 377阅读 0赞

# 目录 #

*  1. 题目
 *  2. 标题
 *  3. 文字
 *  4. 段落
 *  5. 链接和图片
    
     *  5.1 锚点
        
         *  5.1.1 GitHub方式
         *  5.1.2 通用方式
 *  6. 列表
 *  \*7. 引用
 *  8. 表格
 *  9. 代码
 *  10. 分割线及转义字符
 *  11. 流程图

--------------------

在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上为参考)：  
![题目展示效果][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70]

## 2. 标题 ##

标题和HTML的标题标签差不多，也是共有6个不同级别的标题（对应于H1 ~ H6标签），在想要设定为标题的文字前加上`#`号就可以，一个`#`为一级标题，`##`为二级标题，以此类推，最小支持到`######`为六级标题。  
**注意：** `#`后面一定跟一个空格，然后再写标题文字，否则没效果(有些编辑器可能没这么严格)。

# 一级标题 H1
    ## 二级标题 H2
    ### 三级标题 H3
    #### 四级标题 H4
    ##### 五级标题 H5
    ###### 六级标题 H6

效果如下（一下下展示的效果是GitHub上的效果）：  
![标题展示效果图][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 1]

## 3. 文字 ##

文字的常用效果有加粗、倾斜、删除、填充、框选，用`*`号或者`_`号都可以，两种效果显示的一样。突出显示可以用反单引号。删除线不经常用到。基本这些够用了，其他关于设置字体颜色的、给文字填充其他颜色的、给某些文字加上下划线的特效的，你们可以找下其他资料，虽然Markdown支持一些常用的HTML标签，但有时编辑器就会直接忽视掉，这里说下常用，本来Markdown的初衷就应该是通过一些简单的符号快速布局一篇文章，从而专心于写作而不是布局。

*倾斜的文字*
    _倾斜的文字_
    
    **加粗的文字**
    __加粗的文字__
    
    ***斜体加粗的文字***
    ___斜体加粗的文字___
    
    ~~这是加删除线的文字~~
    
    我是一行文字中`突出`显示的文字
    
    我是<kbd>框中</kbd>的文字

GitHub上显示的效果如下：  
![文字显示的效果][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 2]  
文字中还可以插入表情，使用双冒号 `:表情符号码:`，表情符号备忘单可访问https://www.emojicopy.com查看 [Emoji Cheat Sheet][]。  
例：

Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:.

GitHub上显示的效果如下：  
![表情符号显示效果图片][20190324125833813.png]

## 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.

效果如下  
![段落的两种显示方式][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 3]

## 5. 链接和图片 ##

连接有两种形式，一种是图片连接显示，一种是超链接，基本语法为`[超链接名](超链接地址 "超链接title")`，链接中的双引号Title可以写也可以不写，显示图片时前面加上`!`即可。中括号中填写显示的内容(如果是显示图片时表示图片无法显示时替换显示的文字)，括号中写连接或者资源的路径

[Flink 官网](https://flink.apache.org/ "Apache Flink")
    ![Spark GraphX 图片](http://spark.apache.org/docs/latest/img/graphx_logo.png "Apache Spark")

GitHub上展示的效果如下：  
![Markdown连接效果展示][Markdown]

### 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上显示的效果如下：  
![Markdown 列表][Markdown 1]

## \*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预览的效果如下：  
![Markdown 引用显示效果图][Markdown 2]

## 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上显示的效果如下：  
![Markdown 表格在GitHub和CSDN上显示的效果][Markdown _GitHub_CSDN]

## 9. 代码 ##

单行代码可以用一对反单引号包裹起来，如：

Spark读入json文件并加载为DataFrame的语可以用 `val df = spark.read.json("logs.json")` 表示

GitHub显示的效果如下：  
![单行注释GigHub显示的效果图][GigHub]

多行代码块使用一对三个反单引，且两边的反引号单独占一行，常用的代码基本都支持，如python、r、clojure、kotlin、java、scals、groovy、js、angularjs、xml、html、css、yaml、json、bash、sql、hql，更多标注效果可以查看网站(GitLab使用的Rouge库)[http://rouge.jneen.net/。][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上显示的效果如下：  
![GitHub上显示Scala代码的效果图][GitHub_Scala]

## 10. 分割线及转义字符 ##

分割线的效果就如一级或二级标题下面显示的横线，在空行输入三个`*`或者`-`都可以，  
例：

***
    * * * 
    ---
    - - -

GitHub上显示的效果如下：  
![分割线显示的效果图][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 4]  
Markdown需要转义的字符如下，使用本身字符时需要在前面加上\\

\   反斜线  
    `   反引号  
    *   星号  
    _   底线  
    {}  花括号  
    []  方括号  
    ()  括弧  
    #   井字号  
    +   加号  
    -   减号  
    .   英文句点  
    !   惊叹号

左上：未转义的原始字符；右上：未转义时GitHub上显示的效果。  
左下：转义的原始字符；右下：转义后GitHub上显示的效果。  
![转义字符在GitHub上显示的效果图][GitHub]

## 11. 流程图 ##

流程图可以在代码段后加上标识**mermaid**(美人鱼)插件来完成，但是这个支持的不是很好，遗憾的是GitHub上不支持，但是GitLab和CSDN上是可以的。更详细的可以查看 [mermaid https://mermaidjs.github.io/][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图）  
![mermaid表示的Topology图][mermaid_Topology]

End

--------------------

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70]: /images/20220228/cd2dd842766548c092ccaac41b37179d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 1]: /images/20220228/6fde8f3d074f4a3f99400d58486f0c87.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 2]: /images/20220228/3ba48429b1a84eb982e40bf5d417beac.png
[Emoji Cheat Sheet]: https://www.emojicopy.com
[20190324125833813.png]: /images/20220228/77189029fe44470c93eb9d4eefda2585.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 3]: /images/20220228/37d509d274334878aaa99151702a39c4.png
[Markdown]: /images/20220228/bb3261dfd6994fff8436b272802b25d2.png
[Markdown 1]: /images/20220228/1758a78775e24681aadd61e0d2a24003.png
[Markdown 2]: /images/20220228/f1596123ae3c4ead923b8494be2b279e.png
[Markdown _GitHub_CSDN]: /images/20220228/9f422352d9024f0ebad2f52e177d5ed8.png
[GigHub]: /images/20220228/6d07b06320d84a23a0d1623176c434b6.png
[http_rouge.jneen.net]: http://rouge.jneen.net/%E3%80%82
[GitHub_Scala]: /images/20220228/c1be841eee734172b1bd4133515dad4d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dpdGh1Yl8zOTU3NzI1Nw_size_16_color_FFFFFF_t_70 4]: /images/20220228/c8993efc4daf4a2da1309d39de46559e.png
[GitHub]: /images/20220228/91403472ec5a448cbfc0f9e731cd8ea1.png
[mermaid https_mermaidjs.github.io]: https://mermaidjs.github.io/
[Storm]: http://storm.apache.org/
[mermaid_Topology]: /images/20220228/7a534896fb7d40178f88f466c0ecf0dc.png