前言

IT开发，离不开进度项目管理工具。我们主要用的开源的redmine程序(Redmine是用Ruby开发的基于web的项目管理软件)。尤其是在日本IT，使用的尤其多。redmine除了支持html外，还支持Markdown语法。今天主要介绍下markdown的语法。关于redmine请参考redmine网站http://www.redmine.org/。

Markdown简介

Markdown是一种轻量级标记语言，创始人为約翰·格魯伯（英語：John Gruber）。它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档”。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

由于Markdown的轻量化、易读易写特性，并且对于图片，图表、数学式都有支援，目前许多网站都广泛使用 Markdown 来撰写说明文件或是用于论坛上发表讯息。例如：GitHub、reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge等。甚至Markdown能被使用来撰写电子书。

Markdown版本

2004年
John Gruber创造了 Markdown 语言。Markdown： https://daringfireball.net/projects/markdown/

2014年
启动了标准化Markdown项目。由于作者Gruber反对使用Markdown名字，被更名为CommonMark。CommonMark.org发布了规范、参考实现和测试套件的几个版本。CommonMark网站： https://spec.commonmark.org/

2016年
发布了RFC 7763和RFC 7764。RFC 7763从原始变体引入了MIME类型text/markdown。RFC 7764讨论并注册了 MultiMarkdown, GitHub Flavored Markdown (GFM), Pandoc, CommonMark, and Markdown 等markdown变体

2017年
GitHub发布了基于CommonMark的GitHub Flavored Markdown（GFM）的正式规范。

2019年
CommonMark最新版本是0.29 (2019-04-06发布)。

Markdown语法

Markdown语法没有一个统一的标准,不同的工具或平台采用的标准不一样，所以有些语法规则和功能是有差异的。

1.换行

连续2个空格。

1
2
3

这是第一行，后面有两个空格。  
这是第二行,后面没有空格。
这还是第二行。

效果如下:
这是第一行，后面有两个空格。
这是第二行,后面没有空格。 这还是第二行。

2.字体设置-斜体、粗体、删除线

斜体: 用 * 或者 _ 来包括对象，* 或者 _必须成对使用
粗体: 用 ** 来包括对象
加粗斜体: 用 *** 来包括对象
删除线: 用 ~~ 来包括对象

例如：

1
2
3
4
5

*这是斜体*
_这也是斜体_
**这是粗体**
***这是加粗斜体***
~~这是删除线~~

效果如下:

这是斜体
这也是斜体
这是粗体
这是加粗斜体
这是删除线

3.分级标题

分级标题有两种写法，推荐第一种写法。

第一种写法是用#，总共有6级标题。语法如下：
一级标题:用#
二级标题:用##
三级标题:用###
四级标题:用####
五级标题:用#####
六级标题:用######

例如，第一种写法：

1
2
3
4
5
6

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

效果如下:

这是一级标题

这是二级标题

这是三级标题

这是四级标题

这是五级标题
这是六级标题

第二种写法是用 = 和 - 字符来表示，总共有2级标题，= 和 -可以多个连续。语法如下：
一级标题: 用 =
二级标题: 用 -

例如，第二种写法

1
2
3
4

这是一级标题
=
这是二级标题
-

效果如下:

这是一级标题

这是二级标题

4.超链接

Markdown 支持两种形式的链接语法： 行内式和参考式。行内式一般使用较多。

4.1行内式

语法说明：
[链接文字](链接地址 "链接标题")
[]里写链接文字，()里写链接地址, ()中的”“可以为链接指定title属性，title属性可加可不加。title属性的效果是鼠标悬停在链接上会出现指定的title文字。链接地址与链接标题前有一个空格。

例如，鼠标悬停后，第二个网址会提示“None网址”。

1
2

[我的个人网站None](https://inuwashi123.github.io/)  
[我的个人网站None，带有title属性](https://inuwashi123.github.io/ "None网址")

效果如下:
我的个人网站None
我的个人网站None，带有title属性

4.2参考式

参考式超链接一般用在学术论文上面，或者另一种情况，如果某一个链接在文章中多处使用，那么使用引用的方式创建链接将非常好，它可以让你对链接进行统一的管理。

语法说明：
[链接文字][链接标记]
参考式链接分为两部分，[链接文字]和[链接标记]。可以在文本的任意位置添加[链接标记]部分，格式是[链接标记]:链接地址 "链接标题"，链接地址与链接标题前有一个空格。

如果链接文字本身可以做为链接标记，你也可以写成[链接文字][]。可以在文本的任意位置添加[链接文字]部分，格式是[链接文字]：链接地址。

例如，

1
2
3
4

我的网站名字是[None][1]，主要介绍在日本从事IT方面遇到的问题，记录解决方案和学习历程。现在已经发布了[python教程][]。

[1]:https://inuwashi123.github.io/ "None网站"
[python教程]:https://inuwashi123.github.io/tags/python%E6%95%99%E7%A8%8B/

效果如下:
我的网站名字是None，主要介绍在日本从事IT方面遇到的问题，记录解决方案和学习历程。现在已经发布了python教程。

5.自动链接

Markdown支持以比较简短的自动链接形式来处理网址和电子邮件信箱，只要是用<>包起来， Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样，例如：

1
2

我的网站None的网址是<https://inuwashi123.github.io/>。
我的邮箱是<sai.inuwashi@gmail.com>，欢迎大家来信交流。

效果如下:
我的网站None的网址是https://inuwashi123.github.io/。 我的邮箱是sai.inuwashi@gmail.com，欢迎大家来信交流。

6.分割线

你可以在一行中用三个以上的星号(*)、减号(-)、底线(-)来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。

1
2
3
4
5

***
* * *
---
--   -
___

效果如下:

7.代码

插入程序代码的方式有两种，一种是行内代码, 另一种是代码块。

7.1行内代码

语法说明：
`code`
插入行内代码，即插入一个单词或者一句代码的情况，使用`code`这样的形式插入。

7.2代码块

语法说明：
```code
代码内容1
代码内容2
… ```
插入多行代码（也就是插入代码块）。注意： 插入代码块的前方必须有空行。

例如

1
2
3
4
5
6
7
8

测试行内代码，python的`print()`函数

测试代码块，python打印hello world程序
    #include <stdio.h>
    int main(void)
    {
        printf("Hello world\n");
    }

效果如下:

测试行内代码，python的print()函数

测试代码块，python打印hello world程序

1
2
3
4
5

    #include <stdio.h>
    int main(void)
    {
        printf("Hello world\n");
    }

8.引用

在被引用的文本前加上>符号，以及一个空格就可以了，如果只输入了一个>符号会产生一个空白的引用。 两个以上>符号，形成引用的嵌套。两个>就是双层嵌套，三个>就是三层嵌套，以此类推。

例如：

1
2
3
4
5

> 这是第一层引用。注意>后面需要一个空格

>> 这是两层嵌套。注意>后面需要一个空格。

>>> 这是三层嵌套。注意>后面需要一个空格。

效果如下:

这是第一层引用。注意>后面需要一个空格

这是两层嵌套。注意>后面需要一个空格。

这是三层嵌套。注意>后面需要一个空格。

引用其它要素
引用的区块内也可以使用其他的Markdown语法，包括标题、列表、代码区块等。

例如：

1
2
3

> 行内代码`print()`  
> **粗体**
> *斜体*

效果如下:

行内代码print()
粗体
斜体

9.列表

列表分为无序列表和有序列表两种。

9.1无序列表

使用 *，+，- 表示无序列表。符号后面一定要有一个空格，起到缩进的作用。

9.2有序列表

有序列表则使用数字接着一个英文句点。英文句点后面一定要有一个空格，起到缩进的作用。

注意，在使用列表时，只要是数字后面加上英文的点，就会无意间产生列表，比如2019. 这时候想表达的是2019年，有些软件把它被误认为是列表。解决方式：在每个点前面加上\就可以了。

无序列表和有序列表同时使用。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

* 无序列表
+ 无序列表
- 无序列表  

1. 有序列表  
有序列表1的内容。
2. 有序列表  
有序列表2的内容。
3. 有序列表  
有序列表3的内容。

* 1. 无序列表和有序列表混合使用  
无序列表和有序列表混合使用1的内容。
* 2. 无序列表和有序列表混合使用  
无序列表和有序列表混合使用2的内容。
* 3. 无序列表和有序列表混合使用  
无序列表和有序列表混合使用3的内容。

2019\. 表示的是2019年，不是列表2019

效果如下:

  • 无序列表
  • 无序列表
  • 无序列表
  1. 有序列表
    有序列表1的内容。
  2. 有序列表
    有序列表2的内容。
  3. 有序列表
    有序列表3的内容。
  • 1. 无序列表和有序列表混合使用
    无序列表和有序列表混合使用1的内容。
  • 2. 无序列表和有序列表混合使用
    无序列表和有序列表混合使用2的内容。
  • 3. 无序列表和有序列表混合使用
    无序列表和有序列表混合使用3的内容。

2019. 表示的是2019年，不是列表2019

10.插入图片

图片的创建方式与超链接相似，而且和超链接一样也有两种写法，行内式和参考式写法。

语法中图片Alt的意思是如果图片因为某些原因不能显示，就用定义的图片Alt文字来代替图片。 图片Title则和链接中的Title一样，表示鼠标悬停与图片上时出现的文字。 Alt 和 Title 都不是必须的，可以省略，但建议写上。

10.1行内式插入图片

语法说明：
![图片Alt](图片地址 "图片Title")

10.2参考式插入图片

语法说明：
![图片Alt][标记]
在文档的后面需要写上[标记]:图片地址 "Title"

例如：

1
2
3
4
5
6
7

行内式  
![python语言中的索引](C:\test\python\markdown\basic\images\python\Python-Basic-String.PNG "索引的图说明")

参考式
![python语言中的索引][index]

[index]:C:\test\python\markdown\basic\images\python\Python-Basic-String.PNG "索引的图说明"

效果如下:
行内式
python语言中的索引

参考式 python语言中的索引

11.表格

语法说明：

1
2
3

| 标题栏1 | 标题栏2 | 标题栏3 |
| :-: | :-: | :-: |
| 第一行内容1 | 第一行内容2 | 第一行内容3 |
  • |、-、:之间的多余空格会被忽略，不影响布局。
  • 默认标题栏居中对齐，内容居左对齐。
  • -:表示内容和标题栏居右对齐，:-表示内容和标题栏居左对齐，:-:表示内容和标题栏居中对齐。
  • 内容和|之间的多余空格会被忽略，每行第一个|和最后一个|可以省略，-的数量至少有一个

例如,默认的表格样式

1
2
3
4

标题栏1 | 标题栏2 | 标题栏3
- | - | -
第一行内容1 | 第一行内容2 | 第一行内容3
第二行| 第二行 | 第二行

效果如下:

标题栏1 标题栏2 标题栏3
第一行内容1 第一行内容2 第一行内容3
第二行 第二行 第二行

例如,居中对齐表格样式

1
2
3
4

标题栏1 | 标题栏2 | 标题栏3
:-: | :-: | :-:
第一行内容1 | 第一行内容2 | 第一行内容3
第二行| 第二行 | 第二行

效果如下:

标题栏1 标题栏2 标题栏3
第一行内容1 第一行内容2 第一行内容3
第二行 第二行 第二行

例如,第二列居中对齐表格样式

1
2
3
4

标题栏1 | 标题栏2 | 标题栏3
- | :-: | -
第一行内容1 | 第一行内容2 | 第一行内容3
第二行| 第二行 | 第二行

效果如下:

标题栏1 标题栏2 标题栏3
第一行内容1 第一行内容2 第一行内容3
第二行 第二行 第二行

12.反斜杠转义字符

通过上面的学习，我们知道# * < 等字符都是格式化字符，如果我们真的要用这些字符该怎么处理呢？
答案就是反斜杠(\)转义字符。

Markdown为以下字符提供反斜杠转义： 转义字符|中文名称 - | - \|反斜杠 `|反引号 *|星号 _|下划线 {}|大括号 []|方括号 ()|括弧 #|井号 +|加号 -|减号（连字符） .|小数点 !|感叹号

例如：

1
2

\# 这里的#表示的不是一级标题，因为反斜杠将其转义位普通的#字符。  
这里的`表示的也不是行内代码，而是普通的`。

效果如下:
# 这里的#表示的不是一级标题，因为反斜杠将其转义位普通的#字符。
这里的`表示的也不是行内代码，而是普通的`。

参考资料：
维基百科 https://zh.wikipedia.org/wiki/Markdown
Markdown： https://daringfireball.net/projects/markdown/
CommonMark： https://spec.commonmark.org/
Markdown语法：https://daringfireball.net/projects/markdown/syntax https://www.jianshu.com/p/8c1b2b39deb0

转载请注明本网址。