# Markdown
在阅读本章节之前,请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ,请先学习一些 Markdown 教程在新窗口打开。
# 语法扩展
VuePress 会使用 markdown-it在新窗口打开 来解析 Markdown 内容,因此可以借助于 markdown-it 插件来实现 语法扩展在新窗口打开 。
本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。
你也可以通过 markdown 和 extendsMarkdown 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。
# 内置
由 markdown-it 内置支持:
# 标题锚点
你可能已经注意到,当你把鼠标放在各个章节的标题上时,会显示出一个 #
锚点。点击这个 #
锚点,可以直接跳转到对应章节。
# 链接
在你使用 Markdown 的 链接语法在新窗口打开 时, VuePress 会为你进行一些转换。
以我们文档的源文件为例:
└─ docs
└─ zh
├─ guide
│ ├─ getting-started.md
│ ├─ markdown.md # <- 我们在这里
│ └─ README.md
├─ reference
│ └─ config.md
└─ README.md
2
3
4
5
6
7
8
9
原始 Markdown
[首页](/README.md)
[指南](/guide/)
[快速上手](./getting-started.md)
[markdown.links](../reference/config.md#links)
[GitHub](https://github.com)
2
3
4
5
转换为
<RouterLink to="/">首页</RouterLink>
<RouterLink to="/guide/">指南</RouterLink>
<RouterLink to="/guide/getting-started.html">快速上手</RouterLink>
<RouterLink to="/reference/config.html#links">markdown.links</RouterLink>
<a href="https://github.com" target="_blank" rel="noopener noreferrer">GitHub<OutboundLink/></a>
2
3
4
5
渲染为
首页
指南
快速上手
markdown.links
GitHub在新窗口打开
解释
- 内部链接会被转换为
<RouterLink>
以便进行 SPA 导航。 - 指向
.md
文件的内部链接会被转换为目标页面的 路由路径,并且支持绝对路径和相对路径。 - 外部链接会被添加
target="_blank" rel="noopener noreferrer"
属性和一个 在新窗口打开 标记。
# Emoji 🎉
你可以在你的 Markdown 内容中输入 :EMOJICODE:
来添加 Emoji 表情。
前往 emoji-cheat-sheet.com在新窗口打开 来查看所有可用的 Emoji 表情和对应代码。
输入
VuePress 2 已经发布 :tada: !
输出
VuePress 2 已经发布 🎉 !
# 目录
如果你想要把当前页面的目录添加到 Markdown 内容中,你可以使用 [[toc]]
语法。
输入
[[toc]]
输出
目录中的标题将会链接到对应的 标题锚点,因此如果你禁用了标题锚点,可能会影响目录的功能。
# 代码块
下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。
如果你想使用 prism.js在新窗口打开 或 highlight.js在新窗口打开 在客户端进行语法高亮,你可以禁用我们的代码块扩展,然后手动在客户端引入你想要使用的库。
# 语法高亮
VuePress 使用 Prism在新窗口打开 来对代码块进行语法高亮。
Prism 支持多种编程语言,你可以前往 Prism supported languages在新窗口打开 来查看所有可用的编程语言。
你只需要在代码块前添加对应语言的标识符,就可以启用代码高亮:
输入
```ts
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: '你好, VuePress',
}
```
2
3
4
5
6
7
输出
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: '你好, VuePress',
}
2
3
4
5
# 行高亮
你可以在代码块添加行数范围标记,来为对应代码行进行高亮:
输入
```ts{1,6-8}
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: '你好, VuePress',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
```
2
3
4
5
6
7
8
9
10
11
输出
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: '你好, VuePress',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
2
3
4
5
6
7
8
9
行数范围标记的例子:
- 行数范围:
{5-8}
- 多个单行:
{4,7,9}
- 组合:
{4,7-13,16,23-27,40}
提示
行高亮扩展是由我们的内置插件支持的,该扩展 Fork 并修改自 markdown-it-highlight-lines在新窗口打开。
# 行号
你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的,你可以通过配置来禁用它。
你可以在代码块添加 :line-numbers
/ :no-line-numbers
标记来覆盖配置项中的设置。
输入
```ts
// 行号默认是启用的
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```ts:no-line-numbers
// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
2
3
4
5
6
7
8
9
10
11
输出
// 行号默认是启用的
const line2 = 'This is line 2'
const line3 = 'This is line 3'
2
3
// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'
# 添加 v-pre
由于 模板语法可以在 Markdown 中使用,它也同样可以在代码块中生效。
为了避免你的代码块被 Vue 编译, VuePress 默认会在你的代码块添加 v-pre在新窗口打开 指令。这一默认行为可以在配置中关闭。
你可以在代码块添加 :v-pre
/ :no-v-pre
标记来覆盖配置项中的设置。
注意
模板语法的字符有可能会被语法高亮器解析,比如 "Mustache" 语法(即双花括号)。因此,就像下面的例子一样,在某些语言中 :no-v-pre
可能并不能生效。
如果你无论如何都想在这种语言中使用 Vue 语法,你可以尝试禁用默认的语法高亮,然后在客户端实现你的自定义代码高亮。
输入
```md
<!-- 默认情况下,这里会被保持原样 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```
```md:no-v-pre
<!-- 这里会被 Vue 编译 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```
```js:no-v-pre
// 由于 JS 代码高亮,这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```
2
3
4
5
6
7
8
9
10
11
12
13
14
输出
<!-- 默认情况下,这里会被保持原样 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
2
<!-- 这里会被 Vue 编译 -->
1 + 2 + 3 = 6
2
// 由于 JS 代码高亮,这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
2
# 在 Markdown 中使用 Vue
这一章节会介绍 Vue 在 Markdown 中一些基本用法。
可以前往 深入 > Markdown 和 Vue SFC 来了解更多内容。
# 模板语法
我们知道:
- Markdown 中允许使用 HTML。
- Vue 模板语法是和 HTML 兼容的。
这意味着, Markdown 中允许直接使用 Vue 模板语法在新窗口打开。
输入
一加一等于: {{ 1 + 1 }}
<span v-for="i in 3"> span: {{ i }} </span>
2
3
输出
一加一等于: 2
span: 1 span: 2 span: 3
# 组件
你可以在 Markdown 中直接使用 Vue 组件。
输入
这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />
输出
这是默认主题内置的 <Badge />
组件 演示