Markdown 入门手册

Markdown 入门手册

---

写在最前面：这是我个人多年前第一次学习 Markdown 时候的笔记，现存档备份。

---

这是一篇实用文章，适合那些想入手 MarkDown 的初学者。本文旨在推荐 MarkDown 的编辑器和介绍 MarkDown 最核心的详细语法，以便让初学者上手同时有更深的认识。

有关 MarkDown 的介绍请自行搜索资料，本文不作赘述。

---

---

MarkDown 编辑器

工欲善其事，必先利其器

推荐使用 Visual Studio Code 作为 MarkDown 的编辑器来编写 MarkDown 文档。

不推荐使用 Windows 平台的 MarkDownPad 作为编辑器
MarkDownPad 在 Windows10 系统上会出现无法进行实时预览的问题，解决不便
MarkDownPad 的高级功能需要付费使用，我们不建议使用盗版

---

为什么要用 Visual Studio Code

这是一款微软出品的跨平台文本编辑器，它面世虽不到两年，但是发展极为迅速。

Visual Studio Code 不需要任何插件和配置便可以直接编写和预览 MarkDown 文档，界面美观、功能丰富、可自定义，十分适合在 Windows 平台离线使用。

---

Visual Studio Code 的安装与使用

1. 访问 Visual Studio Code 官网 下载最新版本的安装包
2. 安装 Visual Studio Code 安装包
3. 打开 Visual Studio Code ，并新建 .md 格式文件
4. 按下 Ctrl + Shift + V 可以打开实时预览窗口，拖动标签可并排显示代码与预览窗口
5. 推荐安装插件 MarkDown PDF ，可以迅速生成PDF文件，对中文支持比较好

---

MarkDown 语法

---

本文涉及所有的 MarkDown 基本语法，以及 GitHub 扩展语法 GitHub Flavored Markdown（以下简称GFM），并在对应的扩展语法地方做了标注。

MarkDown 扩展语法十分繁多，而且很多扩展语法专注的方面脱离了文本编辑的本质。所以我们建议专注于写作内容，了解最常用的扩展语法便可。

我们坚信写作写的是内容，所思所想，而不是花样格式

---

段落

MarkDown 段落是由一个和多个文本行组成的，并且一个段落前后要有至少一行的空行来隔开

若某一行只包含空格和制表符，则该行也会被视为空行。
普通段落不该用空格或制表符来缩进。

• 示例:

    MarkDown 段落示例（句号后直接回车）。
    这个段落的前后都应该有空行隔开
  

• 效果：

  MarkDown 段落示例（句号后直接回车）。
  这个段落的前后都应该有空行隔开

注意：MarkDown处理多个回车、缩进和空格的方法，一般情况下会简化为一个空格

• 示例:

    两个字        好多空格    直接回车
    好多字        
  

• 效果：

  两个字 好多空格 直接回车
  好多字

在 MarkDown 中如果要在段落中强制产生换行，应该在一行的末尾增加两个空格后再按下回车键

• 示例：

    本文段末尾有两个空格  
    这还是从属于本文段
  

• 效果：

  本文段末尾有两个空格
  这还是从属于本文段

---

标题

MarkDown 中的标题有两种表示法

方法1：使用=或者-
任何数量的 = 和 - 都可产生效果

• 示例1：

    标题1
    =====
    标题2
    -----
  

方法2：使用不同数量的#
# 和 文字之间有至少一个空格
这种写法更为常用

• 示例2：

    # 标题1
    ## 标题2
    ### 标题3
    ……
    ###### 标题6
  

---

区块引用

使用符号 > 可以产生区块引用，同时要注意换行问题
> 和 文字之间不必需要空格，但是为了格式统一，最好还是打上空格。

• 示例：

    >   这是一段引用，背后无空格
    >   这是引用，背后无空格
    >
    >   这是引用，背后有两个空格  
    >   这是引用
  

• 效果：

  这是一段引用，背后无空格
  这是引用，背后无空格

  这是引用，背后有两个空格
  这是引用

多行引用前面的 > 符号，不必在第一行之外的的每行都使用。

• 示例：

    >   这是引用，背后无空格
    这是引用，背后无空格
    这是引用，背后无空格
    
    >   这是引用，背后无空格
        这是引用，背后无空格
        这是引用，背后无空格
  

• 效果：

  这是引用，背后无空格
  这是引用，背后无空格
  这是引用，背后无空格

  这是引用，背后无空格
  这是引用，背后无空格
  这是引用，背后无空格

---

列表

MarkDown 支持无序列表和有序列表。
无序、有序列表的每一项都各占一行

无序列表使用 * + - ，他们的效果是等价的
符号和文字之间有至少一个空格

• 示例：

     * 红
     + 绿
     - 蓝
  

• 效果：

  • 红
  • 绿
  • 蓝

有序列表使用序号和.符号
符号和文字之间有至少一个空格

• 示例：

    1. 红
    2. 绿
    3. 蓝
  

• 效果：

  1. 红
  2. 绿
  3. 蓝

你写的序号值并不影响输出

• 示例：
  ​
  1. 红
  5. 绿

• 效果：

  1. 红
  2. 绿

列表项目可以包含多个段落，但是段落的首行必须缩进对齐

• 示例：

    *   这是段落 
  
        这也是段落
    这行可以缩进也可以不缩进
    
        这也是段落
    这行可以缩进也可以不缩进
    
    *   这是段落
    
    这也是段落，本行未缩进
  

• 效果：

  • 这是段落

    这也是段落
    这行可以缩进也可以不缩进

    这也是段落
    这行可以缩进也可以不缩进

  • 这是段落

  这也是段落，本行未缩进

---

代码

MarkDown 可以方便的处理代码区块，操作方法就是使用一个缩进（相对上一行）

在代码区块，你所书写的一切内容都以原本形式展现出来

• 缩进效果：

    我们需要一个相对上一行的缩进（4个空格）来排版代码
    代码区是原封不动的展现，markdown语法在代码区不适用
    
    #include <stdio.h>
    
    int main(){
        printf("Hello World!\n");
        return 0;
    }
  

MarkDown还支持另一种代码表示法，使用方法是利用符号 ` 或 `` 或 ```，前两者多用于格式化一段代码或者单行代码，后者用于多段代码（```是GFM语法，且支持添加语言标签来显示语法高亮）

• 符号` 或 ``示例：

  `printf("Hello World!\n");`
  ``printf("Hello World!\n");``
  

• 符号` 或 ``效果：

  printf("Hello World!\n");
printf("Hello World!\n");

• 符号```（GFM）：

    ```C
    #include <stdio.h>
  
    int main(){
        printf("Hello World!\n");
        return 0;
    }
    ```
  

• 符号```效果（GFM）：

  #include <stdio.h>
  
  int main(){
      printf("Hello World!\n");
      return 0;
  }
  

---

嵌套

MarkDown 允许标题、段落、代码、引用、列表的相互嵌套

嵌套是使用缩进的对齐来显示层次的，所以最好在使用嵌套时一直保持缩进，并且引用符号 > 最好也在每行都书写

在嵌套中时刻使用预览来修正你的结构

• 示例：

    >   一段引用
        >>  二级引用
        >>  继续引用
        >>  * 列表
    >   * 无序项目1
    >   * 无序项目2
    >   1.  有序1
    >   2.  有序2
    >       
    >       有序2的第二个段落
    >       
    >       有序2的第三个段落
    >           
    >           这里靠缩进产生了有序2下的一个代码块
    >
    >           #include <iostream>
    >           using namespace std;
    >           int main(){
    >               cout << "Hello World!" << endl;
    >           }
    
    >   一段引用
        >>  二级引用
        >>  继续引用
        >>  * 列表
        * 无序项目1
    >   * 无序项目2
    >   1.  有序1
    >   2.  有序2
    >       
    >       有序2的第二个段落
    >       
            有序2的第三个段落去掉 > 后成了代码段
  

• 效果：

  一段引用

  二级引用
  继续引用

  • 列表

  • 无序项目1
  • 无序项目2

  1. 有序1

  2. 有序2

     有序2的第二个段落

     有序2的第三个段落
     ​
     这里靠缩进产生了有序2下的一个代码块

     #include <iostream>
     using namespace std;
     int main(){
         cout << "Hello World!" << endl;
     }
     

  一段引用

  二级引用
  继续引用

  • 列表

  * 无序项目1
  

  • 无序项目2

  1. 有序1

  2. 有序2

     有序2的第二个段落

      有序2的第三个段落去掉 > 后成了代码段
  

注意：从>>退到>时，必须之间要加上一个空引用行 > 作为过渡，否则默认为下一行和上一行是同一级别的引用。

---

分割线

可以采用下面任意一种写法产生分割线

• 示例：

    * * *
    - - -
    _ _ _
  

在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。在符号中间插入空格是允许的。

---

链接

MarkDown 链接有多种形式，行内式、参考式（包括隐式），以及自动链接。

---

行内式

格式：[ 链接文字 ]( 链接地址 “title” )

• 行内式：

  这是[百度](http://www.baidu.com/ "baidu")的链接
  

• 效果：

  这是百度的链接

---

参考式

格式:
[ 链接文字 ][ id ]
[ id ]: 链接地址 “title”

可以选择性地在两个方括号中间加上一个空格: [ ] [ ]
id的链接内容定义可以在文档任意位置
id内容可以有字母、数字、空白和标点符号，但是并不区分大小写

• 参考式:

  这是[百度][1]的链接
  
  [1]: http://www.baidu.com/ "baidu"
  

• 效果：

  这是百度的链接

• 隐式链接：

  这是[百度][]的链接
  
  [百度]: http://www.baidu.com/ "baidu"
  

• 效果：

  这是百度的链接

---

自动链接

自动链接很简单，支持链接和邮箱，使用时候只要加上<>便可以

• 示例：

  <http://www.baidu.com/>
  

• 效果：

  http://www.baidu.com/

在GFM风格的语法中<>不是必须的，可以去掉

• 示例（GFM）：

  http://www.baidu.com/
  

---

图片

插入图片与插入链接的语法十分类似
都要用链接形式来插入

• 例如：

  [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-j4SB0ANe-1594460823042)(/path/to/img.jpg "Optional title")]
  
  ![Alt text][id]
  [id]: url/to/image  "Optional title attribute"
  

---

强调与删除

MarkDown支持使用符号 * 或 _ 实现 倾斜、加粗、加粗倾斜 的强调方式

• 示例：

  _倾斜_  
  **加粗**  
  ***加粗倾斜***
  

• 效果：

  倾斜
  加粗
  加粗倾斜

删除线使用的方法即在文本两边加上 ~ 符号(GFM语法)

• 示例（GFM）：

  ~~删除~~
  

• 效果（GFM）：

  删除

---

表格（GFM）

Markdown（GFM）中表格是使用符号 | - : 来绘制的

• 示例：

  |默认左对齐|左对齐|居中|右对齐|
  |---|:---|:---:|---:|
  |123|123|123|123|
  |123|123|123|123|
  

• 效果：

  默认左对齐	左对齐	居中	右对齐
  123	123	123	123
  123	123	123	123

每行最左边和最右边的 | 可以省去

符号 : 用于设置对齐方式

符号 - 的数量至少有一个

---

任务清单（GFM）

在 Markdown（GFM） 中可以使用任务清单

• 示例（GFM）：

  - [ ] 任务一 未做任务
  - [x] 任务二 已做任务
  

---

反斜杠

在 MarkDown 中使用 \ 符号
可以插入一些在语法中有其它意义的符号（如下所示）：

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

在以上符号前加上 \ 符号 便可以在有其他意义的地方插入原符号

---

@ 、Emoji 和 参考（GFM）

这些只在GFM中使用

• 按下@会出现人员列表，使用方法为：

  @人名
  

• Emoji的使用方法为：

  :name of emoji:
  

• Github可以自动转换参考为链接：

  Any reference to a commit’s SHA-1 hash will be automatically converted into a link to that commit on GitHub.

  Any number that refers to an Issue or Pull Request will be automatically converted into a link.

---

参考链接

MarkDown基本语法-中文教程

GitHub MarkDown教程

MarkDown语法笔记 By PaddingMe

---

文档版本信息

• Version : beta 0.51
• Author : Yun Zhang
• Date : 2017.1.31

©2017 Yun Z. All Rights Reserved.