Markdown语法-基础

1. 标题

Markdown支持两种标题标记语法，我个人常用的是 # 井号标记，使用很简单，在文字前添加 1-6个# ，分别代表1-6级标题。

简洁写法

只在标题开头写标签，以换行为标记语法的结束：

  # h1 //井号标记与标题需要一个以上的空格或者一个水平制表符
  ## h2
  ### h3
  #### h4
  ##### h5
  ###### h6

显示的写出闭合的标记

闭合的 # 井号标记数量不一定需要和起始相同，起始的井号数量已经决定了标题的级别，闭合标记可以明确标题结束位置；通常标题几乎都是独立成行，闭合写法实际使用很少:

  # h1 # //井号标记与标题需要一个以上的空格或者一个水平制表符
  ## h2 ##
  ### h3 ###
  #### h4 ####
  ##### h5 #####
  ###### h6 ######

备注：另外还有一种Markdown标题标记语法，有兴趣可以自行查找，语法书写并不方便，很少用，所以我觉得没必要在这里列出。

2. 首行缩进、换行及段落

首行缩进

由于 Markdown 语法是老外发明的，他们主要考虑的语言体是英文，英语是没有严格的首行缩进，字符占位也和汉语不一样，Markdown 对中文的首行缩进并不太友好，常用这两种方法解决这个问题：

• 把输入法由半角改为全角，两次空格之后就能够有两个汉字的缩进，不过这样做 Markdown 语法转换器有些兼容性并不好；

• 在段落开头的地方，使用特殊占位符，然后紧跟着输入文本即可，占位符所占空白大小是不一样的，一般汉语用全角，英语用半角：

 或  //半角
 或  //全角
 或  //普通空格

## 换行

换行直接敲回车，在有些 Markdown 语法转换器里是不会换行的，解决办法是换行后敲至少两个空格后再回车换行；这个方法其实也只是解决大部分 Markdown 语法转换器的问题，我记得在 Gitlab 在某个版本的时候，这种方法就是不行的；如果遇到这个情况，终极解决办法就是在要换行的地方直接指明写上： `<br/>`

## 段落

段落就是连续行上的文本, 一个或多个还行划分不同的段落，通常一个换行或两个换行为一个段落。

## 3\. 块引用

- Markdown 使用 `>` 标记表示块引用，以换行结束块引用：

这是第一个块引用！

这是第二个块引用！和上一个块引用有换行了

- 块引用可以包含其他 Markdown 标记, 包括标题、列表和代码块等:

包含其他 Markdown 标记的块引用

1. 列表1
2. 列表2

- 块引用可以嵌套,即块引用中包含块引用, 根据层次加上不同数量的`>`标记即可:

一级

二级

三级

## 4\. 列表

### 有序列表

使用 "数字 + `.` 句号标记" 表示有序列表:

1. 列表一 //标记后与列表文本应有一个以上的空格或者一个水平制表符
2. 列表二
3. 列表三
   等价于:
4. 列表一
5. 列表二
6. 列表三
   等价于：
   <ol>
   <li>列表一</li>
   <li>列表二</li>
   <li>列表三</li>
   </ol>

> 备注：如上第二个列表，使用错误的列表序号, 最终生成的列表仍然会以序号1开始；这个特性会导致在实际使用列表中遇上一个场景，在列表与列表之间插入其他的块级元素标记，标签序号上下就对不上号了，下面的列表又重新从1开始，这个问题在某些 Markdown 语法转换器不会出现，但就目前 Markdown 的语法定义来看，这个问题存在是正常的，解决方案见下面的列表使用的注意事项。

### 无序列表

Markdown 使用 `* `星号标记, `+` 加号标记, `-` 连字符标记,这三个标记都可以表示无序列表:

• 列表x //标记后与列表文本应有一个以上的空格或者一个水平制表符
• 列表y
• 列表z
  等价于:

• 列表x
• 列表y
• 列表z
  等价于:

• 列表x
• 列表y
• 列表z
  等价于:
  <ul>
  <li>列表x</li>
  <li>列表y</li>
  <li>列表z</li>
  </ul>

### 列表使用的注意事项

- 如果有序列表项中包含 `>` 块引用标记，则块引用需要缩进，否则下一个列表序号和上一个就不衔接了:

1. 这是一个带引用的列表

   引用内容

2. 这是一个带引用的列表

   引用内容

效果：
1. 这是一个带引用的列表
    > 引用内容
2. 这是一个带引用的列表
    > 引用内容


- 如果列表项中有代码块, 代码块需要双倍缩进8个空格或者两个水平制表符:

• 这是一个有代码块的列表
  <code>

- 终极大招，有些有 Markdown 语法转换器，不管怎么小心还是很容易出现有序列表序号上下不衔接的情况，时候我们就干脆自己定义序号，不触动 Markdown 语法有序列表, 可以通过 `\` 转意标记将点号转意，如下面这样的代码:

3. 列表3
2. 列表2
6. 列表6

效果：  
3\. 列表3  
2\. 列表2  
6\. 列表6

## 5\. 代码块

作为程序员写 Markdown 文档，引代码到文档是经常会用到的，代码块分为行内代码块和多行代码代码块。

### 行内代码块

使用 ` `` ` 标记表示行内代码块，代码块前后各使用一个标记，如下：

Java打印控制台日志通过代码 System.out.println("Hello!"); 实现
等价于：
Java打印控制台日志通过代码<code>System.out.println("Hello!");</code>实现

效果：
Java打印控制台日志通过代码 `System.out.println("Hello!");` 实现

### 多行代码代码块

在要引入的代码每一行都缩进4个空格或者1个水平制表符，就可以表示代码块，不过我更喜欢用标签显得更美观一些，Markdown 使用` ``` ``` ` 标记表示多行代码块，代码块前后各使用三个标记，如下：：

`
public static void main(String[] args) {
System.out.println("Hello!");
}
、、、
等价于：
<pre><code>
public static void main(String[] args) {
System.out.println("Hello!");
}
</code><pre>

### 引入HTML原始码

代码块中， `<` 和 `>` 会自动转成HTML实体 `&lt;` 和 `&lt;` ，代码块标记可以直接引入HTML原始码，例如想在文档中引入一段html代码：

<div class="footer"> © 2016 *** </div>
等价于：
<pre><code><div class="footer">
&copy; 2004 Foo Corporation
</div>
</code></pre>

## 6\. 链接

Markdown 链接的标记语法有"内联式"和"引用式"两种形式，还有一种特殊的自动链接，通常我们程序员内联式使用较多，参考式语法一般用在学术论文上面。

### 内联式语法

`![]` 里写链接文字，`()` 里写链接地址, `()` 中的""中可以为链接指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在链接上会出现指定的title文字),链接地址与链接title前有一个空格，如下：

欢迎点击calmsnow的博客
欢迎点击Atom编写Markdown
等价于：
欢迎点击<a href="https://my.oschina.net/calmsnow/">calmsnow的博客</a>
欢迎点击<a href="https://my.oschina.net/calmsnow/blog/2875493" title="Atom编写Markdown">Atom编写Markdown</a>

### 引用式语法

`[]` 里写链接文字，紧跟着 `:` 链接标记，一个以上的空白符和水平制表符后是链接地址，链接地址后打一个空格，可以为链接指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在链接上会出现指定的title文字)，如下

我的文章[数据结构概述]:https://my.oschina.net/calmsnow/blog/733059
我的文章[Markdown简介]:https://my.oschina.net/calmsnow/blog/2875124 "Markdown简介"

### 自动链接

Markdown 支持一种 "自动" 创建 URL 地址链接的简短形式: 只需用 `<>` 尖括号包围 URL 地址即可：

http://example.com/
等价于：
<a href="http://example.com/">http://example.com/</a>

## 7\. 锚点链接

在网页中，锚点就是网页内的链接跳转，Markdown的锚点链接也是一样的效果，实现跳转到本文档内部的某些位置; [] 里写锚点链接文字, (#) 里面写链接跳转到的字符

跳转到大标题

> 备注：有些Markdown语法转化器只支持在标题后插入锚点，其它地方无效

## 7\. 图片引入

Markdown 图片引入和链接一样，有"内联式"和"引用式"两种形式，通常我们程序员内联式使用较多，参考式语法一般用在学术论文上面。

### 内联式语法

`![]` 里写图片的 alt 属性(图片Alt的意思是如果图片因为某些原因不能显示，就用定义的图片Alt文字来代替图片)，`()` 里写图片地址, `()` 中的 `""` 中可以为图片指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在图片上会出现指定的title文字),图片地址与图片title前有一个空格，如下：

本地图片引入：

远程图片引入：

远程图片

### 引用式语法

`![]` 里写图片的 alt 属性(图片Alt的意思是如果图片因为某些原因不能显示，就用定义的图片Alt文字来代替图片)，紧跟着 `:` 标记，一个以上的空白符和水平制表符后是图片地址，图片地址后打一个空格，可以为图片指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在图片上会出现指定的title文字)，如下

本地图片引入：
![]: /path/mk.img
远程图片引入：
![远程图片]: https://oscimg.oschina.net/oscnet/25ab82.jpg "远程图片"

> 备注：Markdown 提供了图片引入的语法，但是没有指定图片尺寸的支持，如果需要指定图片尺寸, 可以直接使用 HTML 标签 `<img>`。

## 8\. 斜体、加粗、删除线、水平线

### 斜体

Markdown 用星号标记 `*` 或下划线标记 `_` ，代表斜体，相当于用 HTML 标签 `<em>` 包裹,如下：

斜体
等价于：
斜体
等价于：
<em>斜体</em>

### 加粗

Markdown 用两个星号标记 `**` 或两个下划线标记 `__` ，代表加粗，相当于用 HTML 标签 `<strong>` 包裹,如下：

粗体
等价于：
<strong>double asterisks</strong>
三个星号标记加粗斜体：
加粗斜体
等价于：
<strong><em>加粗斜体</em></strong>

### 删除线

Markdown 用两个波浪号标记 `~~`,代表删除线

删除线

### 水平线

一行中只有三个以上的号标记 `*`,或三个以上连字符标记 `-`,或三个以上下划线标记 `_`，则会在该位置生成一个水平线，并换行，星号和连字符之间的空格也是允许的，如下都是生成一条水平线:

---

---

---

---

---

## 9\. 反斜杠转义

Markdown 将很多字符作为标记，那么当在Markdown中想原样输出这些字符，除了用行内代码块的方式以外，还可以使用 `\` 反斜杠转义 Markdown 语法标记符号使之成为字面量，比如：

\
输出：
` backtick
输出：`
*
输出：*
!
输出：！
......

## 10\. 表格

Markdown 标记表格，对于简单表格，应该是比较方便的，通常对于用来写服务端接口文档，多层Json嵌套，需要展现出嵌套感的表格，使用 HTML 标签 `<table>` 会更方便清晰一些；

语法：第一行为表头，列于列之间用`|`竖线标记，第二行分隔表头和主体部分，列于列之间用`-|`标记，第三行开始每一行为一个表格行，列于列之间用`|`竖线标记；表格单元格默认为左对齐，在`-`右边加上`:`就右对齐。

简单方式写写法：

学号	姓名	分数
张三	男	99
李小妹	女	60
王五	男	85

等价于：

学号	姓名	分数
张三	男	99
李小妹	女	60
王五	男	85

为表格第二列指定方向：

帐号	备注
calmsnow	超级活跃
平淡	潜水

## 11\. 注脚

说明注脚最佳的例子就是学术论文，在需要添加注脚的文字后加上脚注名字，在文本的任意位置(一般在最后)添加脚注说明；Markdown 使用`[^注脚名字]`添加脚注：

用 Markdown^[1] 书写文档, 可以转换成 HTML^[2]、 PDF^[3]

> 备注：有些Markdown语法转换器注脚内容与注脚之间必须空一行，不然会失效。上面示例效果如下：<br>
> 用 Markdown[^1] 书写文档, 可以转换成 HTML[^2] 、 PDF[^pdf]

[^1]: Markdown是一种纯文本标记语言
[^2]: HTML是一种标记语言
[^pdf]: 就是pdf，我也不知道怎么描述它

> 还有一些更复杂有趣的Markdown语法，以后有时间再研究了，很多不太常用，本文就简单的总结归纳常用的Markdown基础语法

---

1. Markdown是一种纯文本标记语言 ↩

2. HTML是一种标记语言 ↩

3. 就是pdf，我也不知道怎么描述它 ↩