由于在自己的工作和学习过程中，只查看某个大佬的教程或文章无法满足自己的学习需求和解决遇到的问题，所以自己在追赶大佬们步伐的基础上，又自己总结、整理、汇总了一些资料，方便自己理解和后续回顾，同时也希望给大家带来帮助，所以才写下该篇文章。在本文中，所有参考或引用大佬们文章内容的位置，都附上了原文章链接，您可以直接前往查阅观看。在原文章内容的基础上，若无任何补充内容，同时避免直接大段摘抄大佬们的文章，该情况下也只附上了原文章链接供大家学习。本文旨在总结归纳，并希望给大家提供帮助，未用作任何商用用途。文章内容如有错误之处，望各位大佬指出。如果涉及侵权行为，将会第一时间对文章进行删除。

---

👉 个人博客主页 👈
📝 一个努力学习的程序猿

---

---

VitePress 介绍

笔者在最近发现了一个很好用的工具，又或者说是一个网站框架，迫不及待要跟大家分享。它就是 VitePress。

首先先阐述一下基于 VitePress 的特点，VitePress 能给大家带来什么，能做什么，有什么用（以下内容仅为个人观点，观点不同请轻喷）：

相信各位在工作或学习过程中，肯定或多或少写过文档，常用的可能就是 Word、Markdown 等格式的文档。如果是学生的话，可能就是找一个合适的目录存放文档。如果是工作的话，写文档的数量可能就会很多了，而且通常需要满足多人预览或修改的需求，所以通常会借助一些其他应用，比如：SVN、xx笔记、某在线文档等。

使用上述应用很正常，大家平常也习惯用这些应用。但是这些毕竟都是别人开发好的应用，其中可能会有很多不需要的功能，比如广告等。而且它的样式也就不是我们能决定的了。如果想要自己开发一个前端项目去展示和管理这些文档是否可行？答案就是 VitePress。

VitePress 就是这样的一个所谓的网站框架，使用它可以快速创建一个简单的文档站点。使用的时候我们只需要了解一些简单的配置项，然后在项目里分结构存储 md 文档即可。这样一来，我们可以在除了要写一些必要的 Vue 之外，不用额外写 Vue 代码、不用写任何的样式，使用 VitePress 自带的页面架构和主题，进行文档的存储管理和文档展示（不过和其他应用在页面使用富文本编辑器不同，想要使用 VitePress 需要有基础的开发工具，比如 VSCode、Webstorm 等。然后在这个前端项目里，写基础配置项和 md 文档。也可以通过写代码，调整默认主题、给 md 文档加样式以及满足一些其他的需求）。换句话说，之前用各种应用管理文档，现在使用前端项目提交到 Git 仓库管理，和平常的开发很类似。

总结来说，使用 VitePress 可以快速创建一个简单的文档站点，且整个项目十分轻量，使用起来不繁琐。但是和其他应用对比就会衍生一些需要考虑的问题：首先，如果作为前端开发者来说其实没什么，但写文档的人不一定会 Vue，也可能没接触过 Markdown，这对写文档的人来说就需要上手时间，也需要学习相关用法。就算以上内容不由写文档的人考虑，那么将 Word 文档转成 Markdown 再放到项目中做处理，再提交到 Git 仓库，也无形中增大了管理文档站点人员的工作量，相比于使用现成的应用来说。但是如果真的有展示所有文档的需求，比如你的团队需要整理很多平台相关文档，需要汇报或者给团队内外展示，那么相比于使用其他应用来说，有一个属于自己团队的前端项目，进行页面展示，这显然看起来更有水平，不过确实可能会更费时。也会有些其他场景，比如可以在面试中利用该项目展示自己的技术栈；用该项目建一个自己的个人博客站点等等。所以，如果不考虑费时费力的因素，且确实需要存储并展示文档内容，只考虑最终效果的话，相比于使用其他应用，使用 VitePress 绝对是相对亮眼的选择。如下所示，快速创建站点的页面简单效果：

---

简单明确了它的用途后，现在说回到 VitePress 本身：

首先，它和普通的 Vue 项目不同，从名字上也可以看出来，它使用的是 Vite，而不是老熟人 Webpack。在我的 Vue3 专栏 其实有简单提到过 Vite，Vite 是尤大大开发的一款意图取代 Webpack 的工具。而通过对 Vite 的了解，最后整个项目一定是很轻的。当然 VitePress 必然也不是横空出世的，它的前身就是 VuePress。而推荐 VitePress，就是因为我们的项目可能就是想展示几个文档，基于 Webpack 的项目启动往往就要多出几秒。而 Vite 显然会很好的解决了这些问题：立即启动、按需编译、快速的热更新。

如果您对 Vite 感兴趣，建议您前往官网查看：
https://vitejs.cn/

如果您对 VuePress 感兴趣，建议您前往官网查看：
https://vuepress.vuejs.org/guide/#how-it-works

如果您对 VitePress 感兴趣，建议您前往官网查看：
https://vitejs.cn/vitepress/

其次更关注的就是使用方面。通过这一段时间对 VitePress 的使用，笔者发现 VitePress 真的很简单。它会有多种使用方式，这些用法在文章下方会有相关的使用示例。现在简单来说就是，我们可以直接引用写好的 Markdown 文档，也可以在 Markdown 文档中自由的混合 Vue 组件。它能实现这样操作的核心简述就是（详细原理可前往官网查看）：

每个 Markdown 文档都会使用 markdown-it（https://github.com/markdown-it/markdown-it），涉及到 YAML 的部分还会使用 gray-matter （https://github.com/jonschlinkert/gray-matter）作处理，从而将其编译成 HTML ，然后作为 Vue 组件的模板处理。这就允许我们在 Markdown 文件中直接使用 Vue。在样式方面，我们也可以不做设置，VitePress 中会有一套默认的主题。

最后需要补充的是，在官网中的提示如下：如果使用 VitePress 的情景比较简单，比如只是展示文档那还好。如果想要用于更正式的环境（比如想要商用或大型项目），由于 Vite 仍需要稳定和持续完善，所以不建议使用在任何正式的环境（您也可以选择使用 VuePress，参照上文给出的官方文档）。

【图片截取自 VitePress 中文网】

话不多说，接下来创建 VitePress 项目。

---

创建 VitePress 项目

如果您已经有了一个本地项目，那么可以直接查看第四步。

第一步：找一个合适的位置，创建并进入目录

第二步：在目录中打开终端，输入 npm install -g yarn（如果已经安装 yarn 请看第三步）：

第三步：初始化项目，输入 yarn init，然后输入一些项目基本信息：

第四步：本地安装 VitePress，输入 yarn add --dev vitepress：

第五步：运行项目。输入yarn vitepress dev docs：

也可以在 package.json中添加 scripts 便捷启动，比如：

  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }}
1
2
3
4
5

添加之后，就可以通过输入 yarn docs:dev 运行项目：

第六步：运行后，VitePress 就会在 http://localhost:3000 启动一个热重载的开发服务器，可以前往查看。只不过我们现在没有写任何内容，所以它是 404：

现在，就可以正式开始 VitePress 之旅了！

---

VitePress 基础项目结构

通过前文的内容，我们已经创建了一个VitePress的空项目：

为了更好的使用，在 VitePress 的官方文档中为我们设计了基础的项目结构，只不过需要我们手动创建：

【图片转自 VitePress 中文网】

参照上图，创建完成：

在这里简单说一下文件的功能，关于每个文件更详细的内容将在下文总结。

1、config.js
该文件存储在 .vitepress 目录中，是必要的配置文件。比如可以配置站点的标题、描述、整个站点的页头（页眉）、首页的页脚、跳转其他页面的路由链接，甚至可以配置广告。其中具体的配置项将在下文总结。

2、index.md
该文件就是整个站点的首页。在没有该文件的时候就会像最开始创建项目一样直接进入一个 404 的页面。（其中内容具体怎么使用，将在下文的使用示例中展示）

---

在这里做一个十分简单的示例，给大家体验一下：

index.md：

# 测试
测试首页
1
2

config.js

export default {
    title: 'Hello VitePress', // 站点的标题
    description: '第一个 VitePress' // 站点的描述
}
1
2
3
4

效果：

此时启动项目，就可以发现首页不再是 404 了，而是 index.md 中的内容。且首页的 title 确实已经做了修改。此时可以注意页面导航栏中的页面标签，它的规则是：页面从上到下检索到的第一个h1标题 + | + config.js 中的 title。除此以外，页面标签也有其他的设置方式，而其他方式将在下文预定义变量中着重表述。

---

config.js

config.js 中的内容就像在基础项目结构里展示的那样，需要导出一个 JavaScript 对象。其中它的一些常用配置项总结如下：

【表格总结自 VitePress 和 VuePress 中文网】

举个例子，如果我们做了以下设置（做了该设置需要重启项目查看效果）：

export default {
    base: '/csdn/'
}
1
2
3

那么当我们再次启动项目的时候，它的路径就会是：

在使用的时候需要注意，在配置 base 的时候，需要像上例一样，必须以 / 开头，以 / 结尾。因为 base 会自动的被插入到其他配置中所有以 / 开始的路径之前，所以只需要在 config.js 中指定一次。

最重要的是：一旦设置了 base，就一定需要注意对静态资源的处理。在这里简单提一下，详细内容在下文 静态资源处理 标题说明。

---

export default {
    lang: 'zh-CN'
}
1
2
3

对于这个配置，大家应该不陌生了。它就是来设置页面的语言类型。比如，这个属性将作为 标记渲染到页面HTML中。

注意，lang 属性只会通过 vitepress build 构建站点时添加，通过 vitepress dev 渲染时不会出现。

---

关于该配置，笔者也是在网上找了好久，就是浏览器当前页面标签前面的这个小图标。

后来通过查找找到了设置方式，尊重原作者，您需要前往原文章查看：
https://blog.csdn.net/qq_42460209/article/details/125647447

---

如果需要打包的话，我们先可以使用 vitepress build docs 或 yarn docs:build 试一下。此时我们可以发现，它被打包在了 docs 》 .vitepress 目录中，打包文件名叫 dist。

如果要调整它，我们可以用这样的方式：

export default {
    outDir: './.vitepress/document', // 打包文件从dist改成document
}
1
2
3

---

themeConfig 中有很多配置，如下所示。

---

themeConfig的配置

themeConfig的常用配置：

接下来对 themeConfig 的配置进行一个演示和说明。首先先从顶部导航栏说起。

---

themeConfig使用示例一：顶部导航栏

使用示例：

config.js

export default {
    title: 'CSDN', // 所有文档的浏览器标签title
    description: 'CSDN只爭朝夕不負韶華', // 会渲染成标签
    lang: 'zh-CN',
    themeConfig: {
        siteTitle: 'CSDN只爭朝夕不負韶華',
        logo: '/logo.jpg',
        nav: [
            { text: '菜单1', link: '/menu1/', activeMatch: '/menu1/' },
            { text: '菜单2', link: '/menu2/', activeMatch: '/menu2/' }
        ],
        socialLinks: [
            { icon: 'github', link: 'https://blog.csdn.net/qq_45613931' }
        ],
        footer: {
            message: 'CSDN只爭朝夕不負韶華',
            copyright: 'Copyright © 2022-present CSDN'
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

效果：

相信各位看到效果之后，根据之前表格的介绍，应该能理解各自的使用了，和用例一样使用即可。不过在这里还需要说明一下：nav 、socialLinks、logo（静态资源处理）。

---

themeConfig：nav

对于 nav，其实就是在给顶部导航栏配置一个路由：

{ text: '菜单1', link: '/menu1/', activeMatch: '/menu1/' }

比如上例中，
http://localhost:3000/menu1/ 就会跳转到菜单1的页面里；
http://localhost:3000/menu2/ 就会跳转到菜单2的页面里。

其中，这个路由是由 link 决定的。而 activeMatch 将会决定在什么路由下，对应的菜单会亮起。比如点击菜单1，因为此时的路由是：http://localhost:3000/menu1/，匹配到了 activeMatch ，所以菜单1亮起。

如果你将 activeMatch 改的和 link 不一样，那么你就会发现，当你点击菜单1，菜单1就不会高亮了，但是会进入页面。因此通常 activeMatch 和 link 是一致的。

而点击 菜单1 会进入什么页面呢，这将会从当前项目的目录中寻找。比如这么设置之后：

{ text: '菜单1', link: '/menu1/', activeMatch: '/menu1/' }

那就会在 docs 目录下，找 menu1 的目录，然后默认进入目录下的 index.md。所以我们要像下图这样创建目录：

这样一来，点击 菜单1 就不会是 404 了。

而为什么 /menu1/ 的路径会在 docs 目录下查找，估计是 VitePress 进行了根目录设置。笔者在这里也未进行深究，之后也还会遇到类似的用法，后续再进行说明。但是静态资源的路径需要额外注意，在下文的静态资源处理中有相关说明。

---

themeConfig：socialLinks

然后说一下 socialLinks，比如在上面的使用示例中是这样的。

socialLinks: [
   { icon: 'github', link: 'https://blog.csdn.net/qq_45613931' }
]
1
2
3

我们可以发现，在使用上就是写上了指定的 icon 就会展示对应的图标，点击图标就会跳转进 link 的链接。但这个 icon 明显不是个相对路径或绝对路径，显然是内部组件设定好的，笔者也进行了尝试，试图写入一个相对路径或绝对路径，但不会展示想要的图标。那比如我想把这个图标改成 csdn 的，该怎么做呢？笔者找了好久，百度没有、VuePress没有、VitePress也没有，官方文档中根本找不到答案。那没办法了，只能使用出杀手锏了，直接看源码。

我们从图标入手，找到关键信息：

然后全局搜索肯定能找到这个 github 图标。果不其然，找到了：

我们可以发现，这个图标是个 svg 图标，同时被存储在 VPIconGitHub 组件中。然后再找哪里使用到了 VPIconGitHub。果不其然，找到了：

到了这就发现问题该如何解决了。我们可以看到，socialLinks中有很多的默认图标，比如：facebook、Twitter、YouTube 等等。那我们只需要在这里补充一个想要的图标就行了（svg格式）。

---

顺便再总结一下，如何在这里使用 svg 格式图片：

首先，我们找到一个可用的 png 或 svg 格式图片。笔者一直都在 iconfont 网站中找，在这里也推荐给大家：https://www.iconfont.cn/search/index?searchType=icon&q=csdn

在这里随便下载个想要的图片就OK了（如何下载应该不用详细总结了吧）。

如果用 png 图片也可以，我们找好 png 图片后，随便在网上找一个 png 转 svg 的网站https://www.aconvert.com/cn/image/png-to-svg/ 进行转换就可以了。

当我们拿到 svg 格式的图片后，具体是这样的：

在这个路径下，创建并引入图标的 Vue 组件：

VPIconCSDN 中的 svg 内容，就是把刚才下载的 svg 图片用文本工具打开，将其中 svg 标签的部分拿出来就OK了。

看一下效果：

socialLinks: [
    { icon: 'csdn', link: 'https://blog.csdn.net/qq_45613931' }
]
1
2
3

成功。那么通过源码，我们也就看出来为什么这里的 icon 不能写相对路径、绝对路径了，因为它就是个传参字段，根据传参来展示不同的图标。

---

静态资源处理

之前已经提到过几次需要注意静态资源处理的情况，一次是使用路由 nav 时提到，一次是 config.js 中 base 的配置提到，比如使用路由 /menu1/ 会以 docs 目录为根目录寻找。

而对于如果要使用图片的话，这个路径就需要注意了。比如在 themeConfig 中，对 logo 有这样的设置：

logo: '/logo.jpg',
1

那么它的根目录还会是 docs 目录吗？这个时候，它会去 public 中寻找。也就是说，你需要有这样的一个 public 目录：

如果在 md 文档中引入 public 中的图片，方式是这样的：

![pic](/logo.jpg)
1

因为之前提到过，VitePress 支持在 md 文档中写 Vue，所以最后无论是用 img 标签的方式，还是 md 的方式，一定会碰到相对路径和绝对路径。如果是用相对路径，那肯定没问题。如果是用绝对路径，那就需要注意下面的问题了：

在上文提到了一个关于 base 的配置，比如：

export default {
    base: '/csdn/'
}
1
2
3

这样写的时候，它的路径会是：

那么有过经历的开发者应该发现了，因为路径发生了改变，所以最后部署成功后，就会导致使用绝对路径的图片获取不到。也就是说，此时在文档中使用的绝对路径的图片，现在应该调整成这样：

![pic](/csdn/logo.jpg)
1

需要补充的是：config.js 中使用的绝对路径是不需要加上 base 设定的前缀的。其原因笔者未进行深究。也就是说，在其他地方使用 public 的图片要改成：

![pic](/csdn/logo.jpg)
1

但是在 config.js 中，不需要进行调整：

logo: '/logo.jpg',
1

---

themeConfig 使用示例二：侧边导航栏

使用示例：

config.js （只引入 menu1Siderbar 举例）

import menu1Sidebar from "./menu1Sidebar";

export default {
    title: 'CSDN',
    description: 'CSDN只爭朝夕不負韶華', 
    lang: 'zh-CN',
    themeConfig: {
        siteTitle: 'CSDN只爭朝夕不負韶華',
        logo: '/logo.jpg',
        outlineTitle: '当前页面',
        nav: [
            { text: '菜单1', link: '/menu1/', activeMatch: '/menu1/' },
            { text: '菜单2', link: '/menu2/', activeMatch: '/menu2/' }
        ],
        sidebar: {
            '/menu1/': menu1Sidebar
        },
        socialLinks: [
            { icon: 'csdn', link: 'https://blog.csdn.net/qq_45613931' }
        ],
        footer: {
            message: 'CSDN只爭朝夕不負韶華',
            copyright: 'Copyright © 2022-present CSDN'
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

menu1Sidebar.js

const commonPath = '/menu1';

export default [
    {
        text: '侧边栏1',
        collapsible: true,
        collapsed: false,
        items: [
            { text: '文档1', link: `${commonPath}/a.md` },
            { text: '文档2', link: `${commonPath}/b.md` }
        ]
    },
    {
        text: '侧边栏2',
        collapsible: true,
        collapsed: true,
        items: [
            { text: '文档3', link: `${commonPath}/c.md` },
            { text: '文档4', link: `${commonPath}/d.md` }
        ]
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

目录结构：

效果：

相信各位看到示例后，应该也能理解各自的使用了，和用例一样使用即可。再补充几点就是：参照好用例，创建好目录，然后点击顶部导航栏后，页面就将默认进入对应目录下的 index.md。然后因为设置了 sidebar，所以页面就出现了左侧边栏（不配置 sidebar 的页面就会和普通的页面一样）。

sidebar 的配置也很简单：text 就是侧边栏一级标题；collapsible 就是当前侧边栏是否允许折叠，collapsed 就是当前侧边栏是否在进入页面时默认展开，items 就是侧边栏二级标题和对应的路由。

{
    text: '侧边栏1',
    collapsible: true,
    collapsed: false,
    items: [
        { text: '文档1', link: `${commonPath}/a.md` },
        { text: '文档2', link: `${commonPath}/b.md` }
    ]
},
1
2
3
4
5
6
7
8
9

不过在这里其实没看到右侧边栏，接下来说一下 outlineTitle。

---

themeConfig：outlineTitle

右侧边栏其实不需要配置，它将会根据当前 md 文档的二级标题进行自动设置：

a.md

# 文档1
a.md

## 二级标题1

## 二级标题2
1
2
3
4
5
6

outlineTitle: '当前页面'
1

outlineTitle 就是用来设置右侧边栏的大标题，从上图中可以看到。如果不设置 outlineTitle 的话，它的默认值是 on this page。

---

补充说明

最后还是要补充说明一些内容，显然的是 config 和 themeConfig 的配置肯定远远不止以上内容，以上仅为笔者在使用 VitePress 过程中留意到的常用内容，更多的配置项需要各位参考百度、VuePress、VitePress官网查看。

VitePress
https://vitejs.cn/vitepress/

VuePress
https://v2.vuepress.vuejs.org/zh/reference/default-theme/config.html

不过需要说明的是，之所以这里也推荐查阅 VuePress，是因为 VitePress 的官网给的配置项少的可怜，如上文内容一样，可能需要查源码才能找到该如何配置。而 VitePress 的前身是 VuePress，所以还是有些可以共通的配置项，但是需要自己尝试才能知道在 VitePress 中能不能用。所以如果出现了找不到的配置项，建议大家翻翻源码，是能够发现一些使用方法的，比如全局搜索 outlineTitle 就可以找到默认主题（themeConfig）的配置项：

在默认主题的方法里，甚至还有广告的配置项。感兴趣的话，大家可以查源码查阅。

再比如全局搜索 themeConfig 就可以找到 config 的配置项：

---

VitePress 中 md 文档的基本使用

上文总结了很多配置项，现在终于来到该如何使用的说明上。不过还是先说一些题外话。

首先在文章的开头提到过，这其实是个 Vue 项目，无论是 VuePress 还是 VitePress，它本质上就还是 Vue、Vue Router、Webpack（Vite）驱动的单页应用。不过我们在使用时，创建的文件将是以 .md 为后缀，而不是像 Vue 项目里那样的 .vue，也就是说我们会在 md 文档中编辑我们想要的内容。而它的转换原理在文章的开头和官方文档中都有说明，没注意到的话可以回到顶部查看。其次，在前文的叙述中，提到了使用 VitePress 会有多种使用方式：

1、纯 Vue 用法（但是和写 Vue 还是有区别，详细内容在下文说明）
2、纯 Markdown 文档用法（推荐）
3、YAML + Vue
4、YAML + Markdown（推荐）
5、YAML + Vue + Markdown（推荐）

其中相关的用法，在文章下方会有相关的使用示例。其中笔者个人推荐的方式是 2、4、5。在这里想简单说明一下：首先，我们可以看到部分方式里有使用到 YAML，而 YAML 的作用就是用来给对应文档做一些配置，当然你也可以用 JSON 来做配置，相关的使用在文中下方有相关说明。所以 YAML 并不是一个必选项。而各个方式的优劣性，将在使用示例后总结。

在本文中将不会介绍 Vue 和 Markdown 本身的基础用法，主要是总结在 VitePress 中该如何使用这些内容。其中 3，4，5 使用示例将在下文说明。

由于在 VitePress 用法中，YAML 是比较重要的内容，在其中可以对页面进行相关的配置和主题设定，所以在下文先简单总结一下 YAML 的基本使用方式。如果不想了解 YAML 也没关系，它也可以用 JSON 来替代，您可以直接跳到关于 frontmatter 块的说明部分。

如果想了解关于更多 Vue 的内容，您可以前往我的以下专栏查阅：
Vue 专栏： https://blog.csdn.net/qq_45613931/category_9941207.html
Vue3 专栏：https://blog.csdn.net/qq_45613931/category_10525285.html

如果想了解关于 Markdown 基础使用的内容，由于网上总结的文章有很多，感兴趣的话建议您自行查阅。

除此以外，VitePress 官网还有自己总结的扩展用法，为了避免大篇幅说明和引用，建议您自行前往查阅： https://vitejs.cn/vitepress/guide/markdown.html

---

YAML说明

在本小节将只总结后续需要的用法，更详细全面的内容，为了避免大篇幅引用，您可以前往以下文章查阅：https://www.runoob.com/w3cnote/yaml-intro.html

对于 YAML，可以把它理解成类似于 XML、JSON 文件的一种，通常用作配置文件，配置文件后缀为 .yml。不过 YAML 相比于它们来说会有更精简的语法。在 VitePress 中，通常将使用 YAML 的这部分内容叫做 YAML frontmatter 块。我们将会使用 YAML 精简的语法，以一种紧凑且可读的格式，在 md 文档中存储数据。

YAML 的基本语法如下：
（1）大小写敏感
（2）使用缩进表示层级关系
（3）缩进不允许使用tab，只允许空格
（4）缩进的空格数不重要，只要相同层级的元素左对齐即可
（5）‘#’ 表示注释

YAML 的数据类型如下：
（1）对象：键值对的集合
（2）数组：一组按次序排列的值
（3）纯量：单个的、不可再分的值

---

1、YAML对象

上文提到过 YAML 的语法是很精简的，我们可以简单做个比对。比如我们在 Vue 中写个对象：

form: {
  name: 'csdn',
  test: 'test'
}
1
2
3
4

现在在 YAML 中，我们只需要用缩进表示层级关系即可。比如在以下代码中，它就会将上下行中处于相同缩进层级的行（直到碰到不是一个层级的行为止），作为对象中的数据（下文的相关用法同理，不再赘述）：

form:
  name: csdn
  test: test
1
2
3

在上文的基本语法中提到过，我们还需要注意：缩进不允许使用 tab，只允许空格。缩进的空格数不重要，只要相同层级的元素左对齐即可。

---

2、YAML数组

在使用数组的时候，以 - 开头的行，将会和上下文处于相同缩进层级的行（直到碰到不是一个层级的行），构成一个数组，比如：

list:
  - A
  - B
  - C
1
2
3
4

就相当于：list: ['A', 'B', 'C']

如果是多维数组，那就是：

list:
  -
    - A
  -
    - B
1
2
3
4
5

就相当于：list: [['A'], ['B']]

而我们通常都会从接口获得这样的数据：

tableData: [
  {
	name: 'csdn',
	test: 'test'
  },
  {
	name: 'csdn',
	test: 'test'
  }
]
1
2
3
4
5
6
7
8
9
10

我们现在只要将 YAML 对象和 YAML 数组组合在一起就可以了：

tableData:
    - name: csdn
      test: test
    - name: csdn
      test: test
1
2
3
4
5

这就是在 VitePress 中最常用的用法。

---

3、纯量

纯量就是最基本的值，而对于值大家也知道，肯定有所谓的数据类型。在 YAML 中将会包括：

字符串
布尔值
整数
浮点数
Null
时间
日期

不过我们在 YAML 中使用的时候不用像其他语言那样定义数据类型，也不用太关注数据类型，我们只需要使用即可。简单例子如下（根据类型把它们放在不同的数组、对象中）：

【代码选自菜鸟教程】

boolean: 
    - TRUE  #true,True都可以
	- FALSE  #false，False都可以
float:
    - 3.14
	- 6.8523015e+5  #可以使用科学计数法
int:
    - 123
	- 0b1010_0111_0100_1010_1110    #二进制表示
null:
	parent: ~  #使用~表示null
string:
    - 哈哈
    - 'Hello world'  #可以使用双引号或者单引号包裹特殊字符
    - newline
      newline2    #字符串可以拆成多行，每一行会被转化成一个空格
date:
    - 2018-02-17    #日期必须使用ISO 8601格式，即yyyy-MM-dd
datetime: 
    - 2018-02-17T15:02:31+08:00    #时间使用ISO 8601格式，时间和日期之间使用T连接，最后使用+代表时区
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

---

4、引用

在平常，可能多个对象、数组要复用相同的数据，那就可以使用引用。& 用来建立锚点，<< 表示合并到当前数据，* 用来引用锚点。比如：

defaults: &defaults
  name: csdn

list:
  num: 1
  <<: *defaults

test:
  num: 2
  <<: *defaults
1
2
3
4
5
6
7
8
9
10

它相当于:

defaults:
  name: csdn

list:
  num: 1
  name: csdn

test:
  num: 2
  name: csdn
1
2
3
4
5
6
7
8
9
10

另一个例子:

- &showell Steve
- Clark 
- Brian 
- Oren 
- *showell 
1
2
3
4
5

它相当于:
[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]

以上就是需要了解的 YAML 使用内容。

---

frontmatter 块的说明

在了解了 YAML 的基础用法之后，就可以在每个 Markdown 文档中使用 YAML 了。在每个 Markdown 文档中包含了 YAML 这部分内容的区块就是 YAML frontmatter 块。这个 frontmatter 块将是一个由三个点划线包裹的区块，且这个区块必须位于当前 Markdown 文件的顶部，如果使用 YAML 那么其中必须是有效的 YAML 格式。比如需要这样用（放在 md 文档的顶部）：

---
title: VitePress
titleTemplate: Test VitePress
---
1
2
3
4

在 frontmatter 块中，可以分为三种变量：预定义变量、自定义变量、主题组件变量。

预定义变量就是 VitePress 帮我们设定好的变量，只要在 frontmatter 块中使用，就会带来特定的效果；

主题组件变量就是我们想要使用的某个 VitePress 主题帮我们设定好的变量，只要在frontmatter 块中使用，就会带来特定的效果；

而自定义变量就是没有任何含义和效果，完全是我们自己创建的用于使用的变量。

其中关于预定义变量和主题组件变量的具体说明和使用将在下文展示。

而在上文说明 YAML 的时候也提到了，frontmatter 块主要是存储这些数据的。如果我们想要使用的话，以上的这些变量都可以通过 $frontmatter 调用。这个调用的演示将在下面的使用示例中展示。

除此以外，VitePress 也支持 JSON 格式的 frontmatter，那就需要注意以花括号开始和结尾。比如：

---
{
  "title": "VitePress",
  "titleTemplate": Test VitePress
}
---
1
2
3
4
5
6

而在本文将只使用 YAML frontmatter。

---

使用示例一：YAML frontmatter + Markdown

对于这种方式就很简单了，您依然可以像使用 Markdown 那样，在 YAML frontmatter 的下方书写。如果需要使用预定义变量、自定义变量、主题组件变量时，写入 YAML frontmatter 中即可（具体变量下文说明）。示例如下：

index.md

---
title: VitePress
titleTemplate: Test VitePress
---
# {{ $frontmatter.title }}
首页内容
1
2
3
4
5
6

运行效果如下：

---

使用示例二：YAML frontmatter + Vue

在 md 文档中如果要使用 Vue，和我们平常使用 Vue 会有一点点区别，感兴趣的话可以查看以下内容。您也可以直接查看使用示例三，没有任何区别的，完全的使用 Vue。

使用示例：

index.md

---
title: VitePress
titleTemplate: Test VitePress
---
<style>
.testTitle {
    border: 1px solid black;
}
</style>

<script setup>
const tableData = [
  {
    test: 'test',
    name: 'csdn'
  }
]
const testList = ['1','2','3']
</script>

<div class="testTitle">
  <h1>{{ $frontmatter.title }}</h1>
  <h1>{{ tableData[0].name }}</h1>
  <div v-for="(item, index) in testList" :key="index">
    <h1>{{ item }}</h1>
  </div>
</div>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

运行效果如下：

需要说明的是：style、script、页面主体内容，可以放在 YAML frontmatter 下的任意位置，它们没有先后排列顺序。而在使用上，其实只有 style 和之前用法一样，所以在这里需要额外说明 script 部分和之前Vue的页面 template 部分。

首先说页面的主体内容，也就是平常我们在使用 Vue 时，用 template 包裹的标签部分。在 VitePress 使用时需要注意，此时我们不需要用 template 包裹这些标签，使用的话是会报错的。同时也不需要让这些标签，都在当前 md 文档的一个标签内部。比如这样也是可以的：

<div class="testTitle">
  <h1>{{ $frontmatter.title }}</h1>
  <h1>{{ tableData[0].name }}</h1>
  <div v-for="(item, index) in testList" :key="index">
    <h1>{{ item }}</h1>
  </div>
</div>
<div>不用在一个标签内</div>
1
2
3
4
5
6
7
8

能这样做的原因是：就像文章最开始的时候说到，md 文档最终会在 VitePress 的转换下，变成 Vue 的内容。而查看源码可以发现，它在外层帮我们加好了一层 template，随后利用插槽将转换好的内容，插入到了不同的情况中。在其中也可以看到帮我们设置的 404 页面以及可以根据主题变量 layout ，出现不同的页面效果。具体的 layout 使用会在下文说明，这里只是告诉大家可以不用在乎是否被 template 标签包裹。

除此以外就需要注意，script 要使用