markdown编辑器

Markdown 语法手册&书写风格建议（完整整理版）

2018-03-23  本文已影响8人  5e44ebcb2a17

目录：

兼容HTML

不在 Markdown 涵盖范围之内的标签，都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown，只要直接加标签就可以了。

需要注意的是，只有一些HTML区块元素（区块元素） ——比如 <div>、<table>、<pre>、<p> 等标签，必须在前后加上空行与其它内容区隔开，还要求它们的开始标签与结尾标签，不能用制表符或空格来缩进。

例如：

这是一个普通段落。

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

这是另一个普通段落。

在 HTML区块标签（区块元素） 间的 Markdown 格式语法将不会被处理。

比如，你在 HTML 区块内使用 Markdown 样式的**强调**会没有效果。

HTML 的 区段标签（内联元素） 如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用。

和处在HTML区块标签间不同，Markdown语法在 HTML区段标签（内联元素） 间是有效的。

HTML标签知识补充

什么是HTML区块标签（区块元素）和区段标签（内联元素）？

大多数 HTML 元素被定义为块级元素或内联元素。

块级元素在浏览器显示时，通常会以新行来开始（和结束）。

内联元素在显示时通常不会以新行开始。

HTML块级元素

HTML内联元素

生成目录

在需要生成目录的地方写 [TOC]。

区块元素

段落和换行

一个 Markdown 段落是由一个或多个连续的文本行组成。
段落的前后要有一个以上的空行。

例如：

这是第一个段落。
//空行
这是第二个段落。
//空行
这是第三个段落。
//空行
//空行
这是第四个段落。

Markdown 也允许段落内的强迫换行（插入换行符）。

如果想要 Markdown 段落在 段落内换行 的话，在需要换行的地方输入两个以上的空格然后回车。

书写风格建议

应当尽可能的避免使用换行符（段落内换行 / 两个以上的空格然后回车）， 因为他们没有被广泛认可的语义。

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式。

例：

This is an H1
=============


This is an H2
-------------

书写风格建议

建议：

# Header

# int main //计算机代码

# The header of the example

# The Header of the Example //不建议

# Huge header

Huge header that talks about a complex subject.


# Huge header that talks about a complex subject //不建议

引用

在被引用的内容前加上 > 符号。

例如：

> 这是一段引用内容
>
> 这是一段引用内容

效果如下：

这是一段引用内容

这是一段引用内容

Markdown 也允许只在整个段落的第一行最前面加上 > ：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

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

效果如下：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

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

效果如下：

This is the first level of quoting.

This is nested blockquote.

Back to the first level

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

> ## 这是一个标题。
> 
> 1. 这是第一行列表项。
> 2. 这是第二行列表项。
> 
> 给出一些例子代码：
> 
>     return shell_exec("echo $input | $markdown_script");

效果如下：

  1. 这是第一行列表项。
  2. 这是第二行列表项。

给出一些例子代码：

return shell_exec("echo $input | $markdown_script");

书写风格建议

列表

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

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

- A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

- 一列表项包含一个列表区块：

        <代码写在这>

1986\. What a great season.

无序列表

无序列表使用星号（*）、加号（+）或是减号（-）作为列表标记。

* Red
+ Red
- Red
书写风格建议

建议使用 - ,星号 * 可能和加粗和斜体符号产生混淆，而 + 当前并不流行。

有序列表

有序列表则使用数接着一个英文句点字

//可以这样：
1. Bird
2. McHale
3. Parish

//也可以这样
1.  Bird
1.  McHale
1.  Parish

//甚至不用在意数字的正确性和连续性
3. Bird
1. McHale
8. Parish

很重要的一点是，在列表标记上使用的数字并不会影响输出的 HTML 结果，上面的列表所产生的 HTML 标记为：

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

书写风格建议

//建议
- item 1
- item 2
- item 3

//不建议
- item 1

- item 2

- item 3

多行情况下：

//建议每项空行
- item that
  is wrapped

- item 2

- item 3

//不建议
- item that
  is wrapped
- item 2
- item 3

//建议
Before text.

- list
- list

After text.

//不建议
Before text.
- item
- item
After text.

代码区块

建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以了。

例如：

这是一个普通段落：

    这是一个代码区块。

实际效果为：

这是一个普通段落。

这是一个代码区块。

需要注意的是：一个代码区块会一直持续到没有缩进的那一行（或是文件结尾）。

例如：

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

实际效果为：

Here is an example of AppleScript:

tell application "Foo"
    beep
end tell

代码区块中，一般的 Markdown 语法不会被转换。

表格

Before.

| h    | Long header |
|------|-------------|
| abc  | def         |
| abc2 | def2        |

After.

分隔线（水平横线）

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

* * *

***

*****

---

---------------------------------------

书写风格建议

区段元素

链接

Markdown 支持两种形式的链接语法： 行内式和参考式两种形式。

但是，不管是哪一种，链接文字都是用 [方括号] 来标记。

行内式

在方块括号后面紧接着圆括号并插入网址链接，如果想要加上链接的Title 文字，在网址后面，用双引号把Title文字包起来即可。

例如：

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

以上两句语法最终生成如下：

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

如果要链接到同域的资源，可以使用相对路径：

See my [About](/about/) page for details.

参考式

参考式的链接是在链接文字的括号后面再接上另一个方括号，而在第二个方括号里面要填入用以辨识链接的标记：

This is [an example][id] reference-style link.

也可以选择性地在两个方括号中间加上一个空格：

This is [an example] [id] reference-style link.

接着，在文件的任意处，把这个标记的链接内容定义出来：

[id]: http://example.com/  "Optional Title Here"

链接内容定义的形式为：

  1. 方括号（前面可以选择性地加上至多三个空格来缩进），里面输入链接文字
  2. 接着一个冒号
  3. 接着一个以上的空格或制表符
  4. 接着链接的网址
  5. 选择性地接着 title 内容，可以用单引号、双引号或是括弧包着

注意：网址定义只有在产生链接的时候用到，并不会直接出现在文件之中。

下面这三种链接的定义都是相同：

[id]: http://example.com/  "Optional Title Here" //建议书写此格式
[id]: http://example.com/  'Optional Title Here'
[id]: http://example.com/  (Optional Title Here)

链接网址也可以用方括号包起来：

[id]: <http://example.com/>  "Optional Title Here"

也可以把 title 属性放到下一行，也可以加一些缩进，若网址太长的话，这样会比较好看：

[id]: http://example.com/longish/path/to/resource/here
      "Optional Title Here"

链接辨别标签可以有字母、数字、空白和标点符号，但是并不区分大小写，因此下面两个链接是一样的：

[link text][a]
[link text][A]
隐式链接标记

隐式链接标记功能可以省略指定链接标记，这种情形下，链接标记会视为等同于链接文字，要用隐式链接标记只要在链接文字后面加上一个空的方括号，例如将 "Google" 链接到 google.com，你可以简化成：

[Google][]

然后定义链接内容：

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

书写风格建议

参考样式链接

强调

星号 * 和底线 _ 是作为标记强调字词的符号。

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

效果为：

single asterisks

single underscores

double asterisks

double underscores

注意：

书写风格建议

加粗
斜体

代码

书写风格建议

图片

图片标记和链接的语法很相似，同样也允许两种样式：行内式和参考式。

行内式

[图片上传失败...(image-f9c27f-1521786491657)]

[图片上传失败...(image-2a173b-1521786491657)]

语法定义：

参考式

![Alt text][id]

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

另外，Markdown 无法指定图片的宽高，如果需要的话，可以使用普通的 <img> 标签。

其他

自动链接

用尖括号将网址或电子邮件地址包起来以创建自动链接

<http://example.com/>

所有自动链接必须以字串 http 开始。

反斜杠

利用反斜杠来插入一些在语法中有其它意义的符号。

例如用星号加在文字旁边的方式来做出强调效果

\*literal asterisks\*

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号：

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

参考资料

上一篇下一篇

猜你喜欢

热点阅读