您的位置: 首页  >  文章  >  项目中常用的Markdown语法

项目中常用的Markdown语法

分类: 文章 • 2023-10-27 16:09:22

在Git上创建一个项目时基本都会提示创建一个README.md文件，比如使用GitLab创建一个项目时，在项目下面有如下命令提示：

git clone [email protected]_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上为参考)：
项目中常用的Markdown语法

2. 标题

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

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

效果如下（一下下展示的效果是GitHub上的效果）：
项目中常用的Markdown语法

3. 文字

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

*倾斜的文字*
_倾斜的文字_

**加粗的文字**
__加粗的文字__

***斜体加粗的文字***
___斜体加粗的文字___

~~这是加删除线的文字~~

我是一行文字中`突出`显示的文字

我是<kbd>框中</kbd>的文字

GitHub上显示的效果如下：
项目中常用的Markdown语法
文字中还可以插入表情，使用双冒号 :表情符号码:，表情符号备忘单可访问https://www.emojicopy.com查看 Emoji Cheat Sheet。
例：

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

GitHub上显示的效果如下：
项目中常用的Markdown语法

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.

效果如下
项目中常用的Markdown语法

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语法

6. 列表

列表一般用在写文档的目录结构时，或者在分条叙述时，除了标题可以让文档更有结构层次感外，列表也能有这个效果，但标题用的太多或者太深就感觉文档结构太复杂，主次就凸显的不是很明确了，对于某个标题下的内容如果是由条理的可以用列表布局，如果是有序的可以用有序列表展示。
列表分为无序列表和有序列表。无序列表在开头加上*或者+或者-都OK，然后再结合Tab键就可以布局一个有层次的无序列表。有序列表可以使用序号加空格的形式(点后面需要输一个空格)
例如：

### 无序列表
- 概述
- 属性 Graph
    * 示例属性 Graph
- Graph 运算符
    * 运算符的汇总表
    * 领域聚合
        + 聚合消息 (aggregateMessages)
        + 计算级别信息
    * Caching 和 Uncaching
- Pregel API
  
### 有序列表
1. Storm
2. Spark
3. Flink

GitHub上显示的效果如下：
项目中常用的Markdown语法

*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语法

8. 表格

表格有表头和表Body，表头可以定义缩进的方式

  • :----: 居中
  • :---- 左对齐
  • ----: 右对齐
  • ---- 默认

缩进方式有些可能支持不是很好，如下****是完全支持的，但是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和****上显示的效果如下：
项目中常用的Markdown语法

9. 代码

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

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

GitHub显示的效果如下：
项目中常用的Markdown语法

多行代码块使用一对三个反单引，且两边的反引号单独占一行，常用的代码基本都支持，如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上显示的效果如下：
项目中常用的Markdown语法

10. 分割线及转义字符

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

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

GitHub上显示的效果如下：
项目中常用的Markdown语法
Markdown需要转义的字符如下，使用本身字符时需要在前面加上\

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

左上：未转义的原始字符；右上：未转义时GitHub上显示的效果。
左下：转义的原始字符；右下：转义后GitHub上显示的效果。
项目中常用的Markdown语法

11. 流程图

流程图可以在代码段后加上标识mermaid(美人鱼)插件来完成，但是这个支持的不是很好，遗憾的是GitHub上不支持，但是GitLab和****上是可以的。更详细的可以查看 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或****上现实的效果如下：（左图是Storm原图，右图为用mermaid表示的Topology图）
项目中常用的Markdown语法

End

相关推荐