VuePress

语法扩展

VuePress 会使用 markdown-itopen in new window 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 语法扩展open in new window 。

本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。

你也可以通过 markdownopen in new window 和 extendsMarkdownopen in new window 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。

内置

由markdown-it 内置支持：

标题锚点

各个章节的标题，鼠标放上时，会显示一个 # 锚点。

提示

标题锚点扩展由 markdown-it-anchoropen in new window 支持。

链接

  • 内部链接会被转换为 <RouterLink> 以便进行 SPA 导航。
  • 指向 .md 文件的内部链接会被转换为目标页面的路由路径，并且支持绝对路径和相对路径。
  • 外部链接会被添加 target="_blank" rel="noopener noreferrer" 属性。

建议：对于内部链接，尽可能使用相对路径而不是绝对路径。

Emoji 🎉

你可以在你的 Markdown 内容中输入 :EMOJICODE: 来添加 Emoji 表情。

前往 emoji-cheat-sheetopen in new window 来查看所有可用的 Emoji 表情和对应代码。

提示

Emoji 扩展由 markdown-it-emojiopen in new window 支持。

目录

如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 [[toc]] 语法。

[[toc]]

代码块

下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。

行高亮

你可以在代码块添加行数范围标记，来为对应代码行进行高亮：

输入

```ts{1,6-8}
import type { UserConfig } from '@vuepress/cli'

export const config: UserConfig = {
  title: '你好， VuePress',

  themeConfig: {
    logo: 'https://vuejs.org/images/logo.png',
  },
}
```

输出

import type { UserConfig } from '@vuepress/cli'

export const config: UserConfig = {
  title: '你好， VuePress',

  themeConfig: {
    logo: 'https://vuejs.org/images/logo.png',
  },
}
 




 
 
 

行数范围标记的例子：

  • 行数范围： {5-8}
  • 多个单行： {4,7,9}
  • 组合： {4,7-13,16,23-27,40}

提示

行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 markdown-it-highlight-linesopen in new window。

配置参考： markdown.code.highlightLines

行号

你可以在代码块添加 :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'
```

输出

// 行号默认是启用的
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'

提示

行号扩展是由我们的内置插件支持的。

配置参考： markdown.code.lineNumbers

添加 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 }}
```

输出

<!-- 默认情况下，这里会被保持原样 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}

<!-- 这里会被 Vue 编译 -->
1 + 2 + 3 = 6

// 由于 JS 代码高亮，这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}

提示

v-pre 扩展是由我们的内置插件支持的。

配置参考： markdown.code.vPre

导入代码块

<!-- 最简单的语法 -->
@[code](../foo.js)

<!-- 仅导入第 1 行至第 10 行 -->
@[code{1-10}](../foo.js)

<!-- 指定代码语言 -->
@[code js](../foo.js)

<!-- 行高亮 -->
@[code js{2,4-5}](../foo.js)

<!-- 导入3-10行，指定语言为js，第3行高亮，禁用行号 -->
@[code{3-10} js{3}:no-line-numbers](../foo.js)

需要注意的是，路径别名在导入代码语法中不会生效。你可以通过下面的配置来自行处理路径别名：

module.exports = {
markdown: {
importCode: {
handleImportPath: (str) =>
str.replace(/^@src/, path.resolve(__dirname, 'path/to/src')),
    },
  },
}

<!-- 会被解析至 'path/to/src/foo.js' -->
@[code](@src/foo.js)

提示

导入代码扩展是由我们的内置插件支持的。

配置参考： markdown.importCode

在 Markdown 中使用 Vue

这一章节会介绍 Vue 在 Markdown 中一些基本用法。

可以前往 Cookbook > Markdown 和 Vue SFC 来了解更多内容。

模板语法

输入

一加一等于： {{ 1 + 1 }}

<span v-for="i in 3"> span: {{ i }} </span>

输出

一加一等于：2

span: 1 span: 2 span: 3

组件

可以在 Markdown 中直接使用 Vue 组件。

输入

这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />

输出

这是默认主题内置的 <Badge /> 组件 演示

提示

前往 内置组件 查看所有内置组件。

前往 默认主题 > 内置组件 查看默认主题中的所有内置组件。

注意事项

非标准的 HTML 标签

非标准的 HTML 标签不会被 Vue 模板编译器识别成原生 HTML 标签。相反，Vue 会尝试将这些标签解析为 Vue 组件，而显然这些组件通常是不存在的。 例如：

如果你无论如何都要使用这些标签的话，可以尝试下面两种方法之一：

本网站尊重原创作者，提供页面仅供学习vuepress语法，小鱼资料库