Markdown | VuePress
VuePress指南指南 介绍 快速上手 配置 页面 Markdown 静态资源 多语言支持 部署 主题 插件 打包工具 从 v1 迁移 常见问题 参考参考核心 命令行接口 配置 Frontmatter 内置组件 插件 API 主题 API 客户端 API Node API 打包工具 Vite Webpack 生态系统 默认主题 在新窗口打开 插件 在新窗口打开了解更多了解更多深入 架构 开发插件 开发主题 Cookbook 其他资源 生态系统 在新窗口打开 市场 在新窗口打开 贡献指南 在新窗口打开v2.0.0-rc.8v2.0.0-rc.8 更新日志 在新窗口打开 v1.x 在新窗口打开 v0.x 在新窗口打开选择语言选择语言 English 简体中文 GitHub 在新窗口打开搜索文档K指南指南 介绍 快速上手 配置 页面 Markdown 静态资源 多语言支持 部署 主题 插件 打包工具 从 v1 迁移 常见问题 参考参考核心 命令行接口 配置 Frontmatter 内置组件 插件 API 主题 API 客户端 API Node API 打包工具 Vite Webpack 生态系统 默认主题 在新窗口打开 插件 在新窗口打开了解更多了解更多深入 架构 开发插件 开发主题 Cookbook 其他资源 生态系统 在新窗口打开 市场 在新窗口打开 贡献指南 在新窗口打开v2.0.0-rc.8v2.0.0-rc.8 更新日志 在新窗口打开 v1.x 在新窗口打开 v0.x 在新窗口打开选择语言选择语言 English 简体中文 GitHub 在新窗口打开指南 介绍 快速上手 配置 页面 Markdown 语法扩展 内置 标题锚点 链接 Emoji 🎉 目录 代码块 导入代码块 在 Markdown 中使用 Vue 模板语法 组件 Markdown 插件 注意事项 非标准的 HTML 标签 静态资源 多语言支持 部署 主题 插件 打包工具 从 v1 迁移 常见问题 Markdown在阅读本章节之前，请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ，请先学习一些 Markdown 教程在新窗口打开。语法扩展VuePress 会使用 markdown-it在新窗口打开 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 语法扩展在新窗口打开 。本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。你也可以通过 markdown 和 extendsMarkdown 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。内置由 markdown-it 内置支持：表格在新窗口打开 (GFM)删除线在新窗口打开 (GFM)标题锚点你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 # 锚点。点击这个 # 锚点，可以直接跳转到对应章节。提示标题锚点扩展由 markdown-it-anchor在新窗口打开 支持。配置参考： markdown.anchor链接在你使用 Markdown 的 链接语法在新窗口打开 时， VuePress 会为你进行一些转换。以我们文档的源文件为例：└─ docs
└─ zh
├─ guide
│ ├─ getting-started.md
│ ├─ introduction.md
│ └─ markdown.md # <- 我们在这里
├─ reference
│ └─ config.md
└─ README.md
原始 Markdown<!-- 相对路径 -->
[首页](../README.md)
[配置参考](../reference/config.md)
[快速上手](./getting-started.md)
<!-- 绝对路径 -->
[指南 > 介绍](/zh/guide/introduction.md)
[配置参考 > markdown.links](/zh/reference/config.md#links)
<!-- URL -->
[GitHub](https://github.com)
转换为<template>
<RouteLink to="/zh/">首页</RouteLink>
<RouteLink to="/zh/reference/config.html">配置参考</RouteLink>
<RouteLink to="/zh/guide/getting-started.html">快速上手</RouteLink>
<RouteLink to="/zh/guide/introduction.html">指南 > 介绍</RouteLink>
<RouteLink to="/zh/reference/config.html#links">
配置参考 > markdown.links
</RouteLink>
<a href="https://github.com" target="_blank" rel="noopener noreferrer">
GitHub
</a>
</template>
渲染为首页配置参考快速上手指南 > 介绍配置参考 > markdown.linksGitHub在新窗口打开解释内部链接会被转换为 RouteLink 以便进行 SPA 导航。指向 .md 文件的内部链接会被转换为目标页面的 路由路径，并且支持绝对路径和相对路径。外部链接会被添加 target="_blank" rel="noopener noreferrer" 属性。建议对于指向内部 Markdown 文件的链接，尽可能使用相对路径而不是绝对路径。相对路径是指向目标文件的有效链接，在你的编辑器或者代码仓库中浏览源文件时也可以正确跳转。相对路径在不同 locales 下都是一致的，这样在翻译你的内容时就不需要修改 locale 路径了。提示链接扩展是由我们的内置插件支持的。配置参考： markdown.linksEmoji 🎉你可以在你的 Markdown 内容中输入 :EMOJICODE: 来添加 Emoji 表情。前往 emoji-cheat-sheet在新窗口打开 来查看所有可用的 Emoji 表情和对应代码。输入VuePress 2 已经发布 :tada: ！
输出VuePress 2 已经发布 🎉 ！提示Emoji 扩展由 markdown-it-emoji在新窗口打开 支持。配置参考： markdown.emoji目录如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 [[toc]] 语法。输入[[toc]]
输出语法扩展内置标题锚点链接Emoji 🎉目录代码块导入代码块在 Markdown 中使用 Vue模板语法组件Markdown 插件注意事项非标准的 HTML 标签目录中的标题将会链接到对应的 标题锚点，因此如果你禁用了标题锚点，可能会影响目录的功能。提示目录扩展由 @mdit-vue/plugin-toc在新窗口打开 支持。配置参考： markdown.toc代码块下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。代码标题你可以在代码块添加一个 title 键值对来为代码块设置标题。Input```ts title=".vuepress/config.ts"
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
title: '你好， VuePress',
theme: defaultTheme({
logo: 'https://vuejs.org/images/logo.png',
}),
})
```
Outputimport { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
title: '你好， VuePress',
theme: defaultTheme({
logo: 'https://vuejs.org/images/logo.png',
}),
})
它可以和下列的其他标记一起使用。请在它们之间使用空格分隔。行高亮你可以在代码块添加行数范围标记，来为对应代码行进行高亮：输入```ts{1,7-9}
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
title: '你好， VuePress',
theme: defaultTheme({
logo: 'https://vuejs.org/images/logo.png',
}),
})
```
输出import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
title: '你好， VuePress',
theme: defaultTheme({
logo: 'https://vuejs.org/images/logo.png',
}),
})
行数范围标记的例子：行数范围： {5-8}多个单行： {4,7,9}组合： {4,7-13,16,23-27,40}提示行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 markdown-it-highlight-lines在新窗口打开。配置参考： 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.block导入代码块你可以使用下面的语法，从文件中导入代码块：<!-- 最简单的语法 -->
@[code](../foo.js)
如果你只想导入这个文件的一部分：<!-- 仅导入第 1 行至第 10 行 -->
@[code{1-10}](../foo.js)
代码语言会根据文件扩展名进行推断，但我们建议你显式指定：<!-- 指定代码语言 -->
@[code js](../foo.js)
实际上，[] 内的第二部分会被作为代码块标记来处理，因此在上面 代码块 章节中提到的语法在这里都可以支持：<!-- 行高亮 -->
@[code js{2,4-5}](../foo.js)
下面是一个复杂的例子：导入 '../foo.js' 文件的第 3 行至第 10 行指定语言为 'js'对导入代码的第 3 行进行高亮，即 '../foo.js' 文件的第 5 行禁用行号@[code{3-10} js{3}:no-line-numbers](../foo.js)
需要注意的是，路径别名在导入代码语法中不会生效。你可以通过下面的配置来自行处理路径别名：import { getDirname, path } from 'vuepress/utils'
const __dirname = getDirname(import.meta.url)
export default {
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 来了解更多内容。模板语法我们知道：Markdown 中允许使用 HTML。Vue 模板语法是和 HTML 兼容的。这意味着， Markdown 中允许直接使用 Vue 模板语法在新窗口打开。输入一加一等于： {{ 1 + 1 }}
<span v-for="i in 3"> span: {{ i }} </span>
输出一加一等于： 2 span: 1 span: 2 span: 3组件你可以在 Markdown 中直接使用 Vue 组件。输入这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />
输出这是默认主题内置的 <Badge /> 组件 演示提示前往 内置组件 查看所有内置组件。前往 默认主题 > 内置组件在新窗口打开 查看默认主题中的所有内置组件。Markdown 插件你可以在 VuePress 市场在新窗口打开 上探索更多的 Markdown 插件。注意事项非标准的 HTML 标签非标准的 HTML 标签不会被 Vue 模板编译器识别成原生 HTML 标签。相反，Vue 会尝试将这些标签解析为 Vue 组件，而显然这些组件通常是不存在的。 例如：已废弃的 HTML 标签，比如 <center>在新窗口打开 和 <font>在新窗口打开 等。MathML 标签在新窗口打开，它们可能会被一些 markdown-it 的 LaTeX 插件用到。如果你无论如何都要使用这些标签的话，可以尝试下面两种方法之一：添加一个 v-pre在新窗口打开 指令来跳过这个元素和它的子元素的编译过程。注意所有的模板语法也都会失效。设置 compilerOptions.isCustomElement在新窗口打开 来告诉 Vue 模板编译器不要尝试作为组件来解析它们。 对于 @bundler-webpack ，设置 vue.compilerOptions对于 @bundler-vite ，设置 vuePluginOptions.template.compilerOptions 在 GitHub 上编辑此页 在新窗口打开上次更新: 贡献者: meteorlxy, Mr.Hope 页面 静态资源