Skip to content

Commit 6bd65c8

Browse files
committed
docs: 添加【Markdown 教程-引用语法】
1 parent d12c62f commit 6bd65c8

File tree

2 files changed

+154
-0
lines changed

2 files changed

+154
-0
lines changed

.vitepress/customConfig/sidebar.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ const sidebar: DefaultTheme.Sidebar = {
3131
text: 'Markdown 强调语法',
3232
link: '/md-tutorial/basic-syntax/emphasis.md',
3333
},
34+
{
35+
text: 'Markdown 引用语法',
36+
link: '/md-tutorial/basic-syntax/block-quotes.md',
37+
},
3438
],
3539
},
3640
],
Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
layout: doc
3+
title: Markdown 引用语法
4+
---
5+
# Markdown 引用语法
6+
7+
----
8+
9+
一个块引用标记由 0~3 个空格的初始缩进、一个 `>` 符号与紧随其后的一个空格构成。
10+
11+
[**Example 13**](./block-quotes.md#eg13) {#eg13}
12+
13+
<DemoBlock :list="[
14+
'> Quote',
15+
]" />
16+
17+
块引用具有如下特点:
18+
19+
1. 连贯性:如果一连串单行的块引用 L 组成了一个序列 S,那么这时候的结果就是单个包含 S 的块引用。
20+
2. 懒惰性:如果一连串单行的块引用 L 组成了一个序列 S,那么从某一行(首行除外)甚至多行的行首删除引用标记不会影响这个块引用的最终渲染结果。
21+
3. 顺序性:同一行内不能同时使用两个引用标记。
22+
23+
## 用法
24+
25+
以下是块引用的标准用法:
26+
27+
[**Example 14**](./block-quotes.md#eg14) {#eg14}
28+
29+
<DemoBlock :list="[
30+
'> Quote Example',
31+
]" />
32+
33+
----
34+
35+
`>` 符号后的空格可以省略,不影响最终渲染的结果:
36+
37+
[**Example 15**](./block-quotes.md#eg15) {#eg15}
38+
39+
<DemoBlock :list="[
40+
'>Quote Example',
41+
]" />
42+
43+
----
44+
45+
块引用的内容可以为空白内容:
46+
47+
[**Example 16**](./block-quotes.md#eg16) {#eg16}
48+
49+
<DemoBlock :list="[
50+
'>',
51+
'>\n>\n',
52+
]" />
53+
54+
----
55+
56+
若要分隔块引用,可以使用[段落语法][p:para-eg2]将两个块引用分隔开:
57+
58+
<DemoBlock :list="[
59+
'> foo\n\n> bar',
60+
]" />
61+
62+
同理,如果要在一个块引用中分两个段落,则只需要在段落语法的基础上,每行起始添加一个段落的符号即可。
63+
64+
<DemoBlock :list="[
65+
'> Quote 1\n>\n> Quote 2',
66+
]" />
67+
68+
----
69+
70+
### 懒惰性的具体用法
71+
72+
基于块引用的懒惰性,对于一连串单行的块引用序列,从第二行开始,`>` 符号都可以省略,但唯独不能删除第一行的 `>` 符号,否则无法构成块引用:
73+
74+
[**Example 17**](./block-quotes.md#eg17) {#eg17}
75+
76+
<DemoBlock :list="[
77+
'> Quote 1\nQuote 2\nQuote 3',
78+
]" />
79+
80+
这种省略有一定局限性,详见 [注意事项][p:cautions]
81+
82+
----
83+
84+
### 关于缩进
85+
86+
`>` 符号前最多可以支持 1~3 个空格的缩进,不影响最终渲染的结果:
87+
88+
[**Example 18**](./block-quotes.md#eg18) {#eg18}
89+
90+
<DemoBlock :list="[
91+
'> Quote 1\n > Quote 2\n',
92+
]" />
93+
94+
但如果使用了超过 4 个空格的缩进,则会变成代码块:
95+
96+
[**Example 19**](./block-quotes.md#eg19) {#eg19}
97+
98+
<DemoBlock :list="[
99+
' > Quote 1\n > Quote 2',
100+
]" />
101+
102+
----
103+
104+
### 分隔不同的块引用
105+
106+
若要另起一个块引用,需要在块引用之间使用回车隔开一行:
107+
108+
[**Example 20**](./block-quotes.md#eg20) {#eg20}
109+
110+
<DemoBlock :list="[
111+
'> Quote 1\n\n> Quote 2',
112+
]" />
113+
114+
115+
## 注意事项 {#cautions}
116+
117+
1.[**Example 17**][p:eg17] 中,我们提到了引用符号在某些情况下可以省略,但这种省略仅限于那些本来就应该视作是段落的延续的行,比如在下列示例中:
118+
119+
```markdown
120+
> foo
121+
> ---
122+
```
123+
124+
在不改变原有意思的情况下,第二行的 `>` 就不能省略:
125+
126+
[**Example 21**](./block-quotes.md#eg21) {#eg21}
127+
128+
<DemoBlock :list="[
129+
'> foo\n---',
130+
]" />
131+
132+
相似地,还有以下不能省略的情况:
133+
134+
[**Example 22**](./block-quotes.md#eg22) {#eg22}
135+
136+
<DemoBlock :list="[
137+
'> - foo\n- bar',
138+
]" />
139+
140+
[**Example 23**](./block-quotes.md#eg23) {#eg23}
141+
142+
<DemoBlock :list="[
143+
'> ```\nfoo\n```',
144+
]" />
145+
146+
在 Example 22、23 中,省略第二行及后续行的引用标记会导致引用在第一行结束。
147+
148+
[p:para-eg2]: ./para-and-line-breaks.md#eg2
149+
[p:cautions]: block-quotes.md#cautions
150+
[p:eg17]: block-quotes.md#eg17

0 commit comments

Comments
 (0)