Markdown 彻底指南

时间  2019-11-12 标签 markdown 彻底 指南

概述

Markdown 是一种用于网络文本书写的轻量级标记语言，普遍用于我的 blog、github、wiki 中。其实浏览器并不能识别 Markdown 的语法，但许多 blog、wiki 平台以及 github 都内置了 Markdown 编辑器，编辑器会先把 Markdown 文本转换成 HTML 格式的网页，而后再把 HTML 网页交给浏览器来显示。除了上述的内置编辑器外，还有许多能解析 Markdown 语法的编写工具，这些工具通常都提供浏览器预览和导出成 HTML 或 PDF 文件的功能。javascript

Markdown 的语法由一些符号定义，这些符号夹杂在文本中，用于控制文本的显示方式。好比两个星号能够给文字加粗**加粗**，这两个星号在 Markdown 编辑器处理后就变成了 HTML 中的<strong>加粗</strong>标签。相较于 Word 类型编辑器的“所见即所得”而言，Markdown 文件自己是纯文本，并无格式，但经过 Markdown 语法符号能提供更加准确的 HTML 类型格式控制同时又没有 HTML 那么难以书写。php

Markdown 的语法须要编辑器才能实现，所以编辑器能够按照本身的需求添加或者修改某个语法的含义。所以，基本上全部编辑器解析 Markdown 语法的方式都有些许差别，但大致上能够分红三类：html

  • Classic Markdown：最基础的 Markdown 语法，全部的编辑器都支持
  • Extra Markdown：扩展的 Markdown 语法，增长了表格等元素，不必定都能支持
  • Github Markdown：github 文档使用的 Markdown 语法，包含 Extra Markdown 的全部内容，还增长了代码高亮、emoji表情等语法，目前许多 blog 平台（cnblogs，csdn）都支持这种语法

本文主要介绍 Classic 和 Github 的语法，对于只有 Github 支持的语法会用上标\(^g\)注明，同时就在使用 Markdown 中常常遇到的问题给出解决方案。做者但愿能在一篇文章中将 Markdown 使用中常常遇到的问题作全面总结，如有错漏，欢迎指正。java

注：做者在编写此文的过程当中发现 cnblogs 的 Markdown 编辑器有个别地方处理不符合标准，代码块和引用块的默认样式有点丑，而且不支持预览，请各位斟酌后使用。git

语法

标题和段落

标题支持两种语法：底线格式和井号格式。标题会转换成 HTML 中的<h1><h2>等标签，这对于自动生成目录很是重要（Markdown 没有自动生成目录的语法，不过能够利用其余的方式）。github

底线格式须要单独一行，使用至少两个=或-，只能处理两阶的标题。shell

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

井号格式使用 1～6 个的#，最多六阶标题。行尾能够添加任意个#号，并不会被看成标题的一部分。编程

# 标题1 #
## 标题2
###### 标题6 ##


段落开头不能使用空格或制表符缩进，连续的文本行会首位相连成为一个段落（cnblogs编辑器不会合成段落）。不一样段落之间须要用一个或多个空行（空行能够包含空字符）分隔。若是想将连续的文本行解释为两个段落，在第一个文本上的末尾键入两个空格后再换行。在生成 HTML 时，段落开头的空格会被忽略或被解释为代码块等格式，段落之间的全部空行都会被忽略。ubuntu

行首空格、段间空行都被忽略。
连续文本行会被合成一段。（cnblogs编辑器仍然是两段）


能够在第一行最后加两个空格后换行  
就能够分段了。

行首空格、段间空行都被忽略。
连续文本行会被合成一段。（cnblogs编辑器仍然是两段）api

能够在第一行加两个空格后换行
就能够分段了。

连接和图片

连接用于跳转到其余页面，包含行内式和参考式两种样式，还可使用简单的自动连接。跳转地址能够用/开头的相对路径引用本机资源。

行内式：连接文字和跳转地址写在一块儿。如：
[an example](http://www.cnblogs.com/zhuyuanhao/ "连接title")
an example

参考式：连接文字和跳转地址分开写，经过[id]标识联系起来。[id]标识能够包含字母、数字、空白和标点符号，可是并不区分大小写。跳转地址部分能够出如今文件的任意地方。

This is [an example][ID 2] reference-style link.

[id 2]: http://www.cnblogs.com/zhuyuanhao/ "可选title, 能够用单引号'、双引号"或括号()包着，也能够另起一行并缩进"
[iD 3]: <http://www.cnblogs.com/zhuyuanhao/> 
    '跳转地址也能够用尖括号包起来'

隐式参考连接：使用空标识[]，在跳转地址处使用连接文字做为标识。

[Google][]

[Google]: http://google.com/ "Google Inc."

自动连接：对于网址和电子邮件信箱，只要是用尖括号包起来，Markdown 就会自动把它转成连接，连接文字和跳转地址相同。

<http://www.cnblogs.com/zhuyuanhao/>
<address@example.com>

http://www.cnblogs.com/zhuyuanhao/
address@example.com

图片用于在当前页面显示图片，也包含行内式和参考式，只须要在连接的样式前加一个惊叹号!，就会被识别为图片。可使用相对路径引用本地的图片，也能使用 url 引用其余网站的图片。不过到目前为止，Markdown 尚未办法指定图片的宽高。

行内式：
![Alt text](/path/to/img.jpg "Optional title")

参考式：

![Alt text][id]

[id]: url/to/image  "Optional title attribute"

引用块

引用块使用右尖括号>标识，能够在每行都加上>，也能够只在段落的第一行加>。

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

> Donec sit amet nisl. 
 Aliquam semper ipsum sit amet velit. Suspendisse
 id sem consectetuer libero luctus adipiscing.

可使用多个>表示引用块的不一样层级。

> This is the first level of quoting.
> 
> > This is nested blockquote.
> 
> Back to the first level.

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

> ## This is a header.
> 
> 1.   This is the first list item.
> 2.   This is the second list item.
> 
> Here's some example code:
> 
>     return shell_exec("echo $input | $markdown_script");

代码

代码能够用行内代码或者代码块来表示。
行内代码使用一个或多个重音符号来表示代码区域，起始和结束的重音符号个数必须相同。

Use the `printf()` function.

Use the printf() function.

若是想在代码区域内插入k个重音符号，能够用k+1个重音符号来开启和结束代码区段。

There is a literal ```backtick (``)``` here.

There is a literal backtick (``) here.

若是在起始和结束端都插入空格，就能够在区域的一开始就插入重音符号。

A single backtick in a code span: `` ` `` 
A backtick-delimited string in a code span: `` `foo` ``

A single backtick in a code span: `
A backtick-delimited string in a code span: `foo`

Classic 代码块使用每行缩进的 4 个空格或是 1 个制表符来表示。在转换成 HTML 时，每行行首的 4 个空格或 1 个制表符缩进会被移除，其他的空格或制表符会被保留。另外，通常在代码块中的 Markdown 语法符号不会被转换。

Here is an example of AppleScript:

    tell application "Foo"
        **beep**
    end tell

Here is an example of AppleScript:

tell application "Foo"
    **beep**
end tell

Github 代码块使用三个或以上重音符号(```)放在代码块的前一行和后一行。在前一行重音符的后面加上语言名称，能够按照该语言的语法对代码块内容高亮。若是要在代码块中显示三个重音符，用四个重音符来表示代码块起止便可。支持的编程语言参见the languages YAML file，若是要使用没有语法高亮的代码块，用plain标记。

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

列表

列表包括无序列表和有序列表两类。列表的每一项都使用标记 + 分隔（至少一个空格或制表符） + 段落的格式，段落的内容能够跨行，用空格缩进，还能够包含代码块、引用块等。若是在一个列表项里添加用空行隔开的多个段落，须要在每一个段落开头添加至少两个空格。若是要表示多级列表，须要在下一级列表标记前加上至少两个空格或一个制表符，多级列表能够混用不一样的标记（cnblogs的 Markdown 不支持多级列表）。

无序列表使用星号*、加号+或是减号-做为列表标记，标记不能混用，不然会视为不一样的列表。
有序列表则使用数字和一个英文句点表示，数字的内容是任意的，并不会影响 HTML 显示的数字。有时不须要列表，但在段落开头的文字是数字加句点的格式，为了避免被 Markdown 解析成列表，须要在句点前加上反斜线，如：2016\. Something Begin.

+ 无序列表项1
+ 无序列表项2
 + 下一级列表
   2. 再下一级列表1
   2. 再下一级列表2
- 不一样标记视为不一样列表
- 列表还能够
```c
# 包含代码块
int a = 10;
```
- 或者引用
> I have a dream!
- 以及多行或多段。
第二行

  第二段

2016\. Something Begin.

表格\(^g\)

表格只能用在Extra Markdown或Github Markdown中。用竖线|和连字符-表示，竖线用于分隔表格中的不一样列，连字符用于分开表头和表格主体，连字符添加冒号:还能够控制单元格对齐方式。书写时，竖线没有对齐要求，行首行尾的竖线能够省略，表头下须要至少三个连字符分隔。

表格内容能够包含 Mardown 行内格式，不能添加引用、列表、多行文本，能够包含代码行，不能用代码块。若要书写竖线，须要用反斜线转义\|（cnblogs编辑器支持有问题）。

| 默认左对齐 | 左对齐 | 中对齐 | 右对齐 |
| ------    | :--- | :---: | ---: | 
 头尾的竖线能够省略 | 对齐 | 对齐 | 对齐  
| **加粗** | `int a;` | 竖线 \| | 连接[Google](www.google.com) |
默认左对齐 左对齐 中对齐 右对齐
头尾的竖线能够省略 对齐 对齐 对齐
加粗 int a; 竖线 | 连接Google

文字样式和转义符号

文字样式包括加粗、斜体、删除线。其中 Classic Markdown 不支持删除线。加粗用**或__表示，斜体用*或_表示，删除线用~~表示。若是样式符号两边都没有文字的话，会被看成普通符号，如：** 符号 **效果为 ** 符号 **

样式 语法 举例 效果
加粗 **或__ **文本**或 __文本__ 文本或 文本
斜体 *或_ *文本*或 _文本_ 文本或_文本_
删除线 ~~ ~~文本~~ 文本
混合 将上述符号混合 **~~文本~~*混合* **效果 文本混合 效果

对于 Markdown 中的语法符号，前面加反斜线\便可显示符号自己。包括

\\ 反斜线 
\` 重音号 
\* 星号 
\_ 下划线 
\{\} \[\] \(\) 括号 
\# 井号 
\+ 加号 
\- 减号 
\. 句点 
\! 惊叹号

\ 反斜线
` 重音号
* 星号
_ 下划线
{} [] () 括号
# 井号
+ 加号
- 减号
. 句点
! 惊叹号

分割线用三个以上的星号*、减号-或下划线_表示，符号之间能够用空格分开但行内不能有其余非空白符号。

*** 
- - -
_______

任务列表\(^g\)和emoji表情\(^g\)

Github Markdown 支持任务列表样式和 emoji 表情符号。（cnblogs编辑器里，这两项的支持都不是很好）

任务列表须要在 Markdown 列表项的段落部分用[ ]开头，也能够用[x]开头表示一个已选择的任务项。

- [x] 学习 Markdown
- [ ] 使用 Markdown
  1. [ ] 写博客

emoji表情使用:EMOJICODE:的格式，详细的表情列表参见EMOJI CHEAT SHEET。

:man: :thumbsup: :sunny: :bug:

在 Github 平台还有两个特殊的功能：使用@user/team来通知用户或者用户组或使用#number引用某个 Issue 或者 Pull Request。这两个功能只在 Github 平台有效，这里就不详述了，能够参考mentioning-users-and-teams。

HTML 标签

Markdown 中能够直接书写大部分 HTML 标签。其中在 HTML 的区块类型标签<div>、<table>、<pre>、<p> 等内的，Markdown 语法会失效，在 HTML 行内型标签<span>、<cite>、<del> 等内，Markdown 语法仍然有效。须要注意的是，在 HTML 标签内，书写特殊字符 < 和 & 仍然须要用它们的替代形式 &lt; 和 &amp;表示。在 Markdown 中，也能用 < 和 & 的这种特殊形式。

This is <a href="http://cn.bing.com/images/search?q=markdown&amp;go=Submit+Query">Markdown</a>  regular paragraph. 
1 < 3 & 5
2 &lt; 4 &amp; 6
<table border="1" bgcolor="yellowgreen">
    <tr>
        <td>**count** 1 </td>
    <td>**count** 2 &lt; 4 &amp; 6</td>
    </tr>
</table>
This is **<em>another regular** paragraph</em>.

This is Markdown regular paragraph.
1 < 3 & 5
2 < 4 & 6






count 1 count 2 < 4 & 6

This is another regular paragraph.

支持 Tex 公式

在 Markdown 中添加 Tex 公式有两种方式：请求外部服务器生成或者本地生成

外部服务器生成方式是发送 Tex 公式到外部服务器，而后服务器会将 Tex 公式的图片发送回来，这种方式不能处理复杂的 Tex 语法。使用 HTML <img>标签，将 Tex 公式写在 <img>标签的 url 连接的参数里。如：
Google Chart服务器

<img src="http://chart.googleapis.com/chart?cht=tx&chl=\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">

forkosh服务器

<img src="http://www.forkosh.com/mathtex.cgi? \Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">

本地生成方式将 Tex 解析脚本插入到 HTML 文件的<head>标签中，在 HTML 文件渲染的过程当中生成 Tex 公式，当网页中 Tex 公式比较多时速度会变慢。推荐使用 MathJax 引擎来实现，经过将下列 JS 脚本嵌入到生成的 HTML 文件<head>标签中，就能解析 Tex 公式了。Markdown 文件不该包含 <script> 标签，通常是经过修改 Markdown 编辑器的设置来自动添加。

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

行间公式（$$Tex$$）：$$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$
\[x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\]
行内公式（$Tex$或\\(Tex\\)）：\\(x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\\)
\(x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\)

csdn 的 Markdown 编辑器默认支持 Tex 公式，cnblogs 须要在博客“选项”中选中“启用数学公式支持”，MarkdownPad2 须要在Tools > Options > Advanced > HTML Head Editor中添加 MathJax 引擎，在F6预览中显示 Tex 公式。

免费编辑器

书写 Markdown 离不开编辑器。这里罗列各个平台下的免费编辑器供参考

平台 编辑器
Windows MarkdownPad2
Mac Mou
Linux ReText
线上编辑器 Dillinger.io、StackEdit
博客平台 cnblogs、csdn、简书
Chrome插件 Markdown Preview Plus

另外，Sublime、Vim都带有 Markdown 预览插件。

免费图床

Markdown 文件自己不能包含图片。所以，要发布带图片的 Markdown 文章，就须要先将图片存放在网络上，经过 url 地址引用图片：![desc](url)。博客平台通常会提供图片上传服务，这样就能够在博客中引用图片的 url ，可是转发到博客外部就不必定能访问。网络图床服务器中的图片能在全部地方访问，但也有网络失效或者服务器关闭的风险。

这里罗列几个比较好用的图床服务器

地址 说明
https://sm.ms/ 国际图床，无注册、不限流量
Github 能够把图片上传到github上
https://portal.qiniu.com 国内云存储服务七牛云，需注册、有流量限制，但能够本身控制
http://yotuku.cn/ 国内图床，无注册、不限流量

参考连接

Classsic Markdown：http://daringfireball.net/projects/markdown/syntax/
Classsic Markdown的翻译版：http://wowubuntu.com/markdown/
Extra Markdown：https://michelf.ca/projects/php-markdown/extra/
Github Markdown：https://help.github.com/categories/writing-on-github/
MathJax：https://www.mathjax.org/

联系我们 沪ICP备13005482号-10