关于frontmatter

frontmatter 支持基于页面的配置。在每个 markdown 文件中，可以使用 frontmatter 配置来覆盖站点级别或主题级别的配置选项。此外，还有一些配置选项只能在 frontmatter 中定义。

VitePress 支持在所有 Markdown 文件中使用 YAML frontmatter，并使用 gray-matter 解析。frontmatter 必须位于 Markdown 文件的顶部 (在任何元素之前，包括 <script> 标签)，并且需要在三条虚线之间的采用有效的 YAML 格式。例如：

yaml

---
title: Docs with VitePress
editLink: true
---

许多站点或默认主题配置选项在 frontmatter 中都有相应的选项。可以使用 frontmatter 来覆盖当前页面的特定行为。详细信息请参见 frontmatter 配置参考。

可以通过 Vue 表达式中的 $frontmatter 全局变量访问 frontmatter 数据：

markdown

{{ $frontmatter.title }}

frontmatter的示例

如果是使用pnmp部署的vitepress，则其默认就生成了一个主页(index.md)，其内容大致如下：

yaml

---
layout: home

hero:
  name: "My Awesome Project"
  text: "A VitePress Site"
  tagline: My great project tagline
  actions:
    - theme: brand
      text: Markdown Examples
      link: /markdown-examples
    - theme: alt
      text: API Examples
      link: /api-examples

features:
  - title: Feature A
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
  - title: Feature B
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
  - title: Feature C
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
---

访问 frontmatter 数据

在三点划线之间，你可以设置预定义变量，甚至可以创建自定义变量。这些变量可以通过$frontmatter调用。

这是一个如何在Markdown文件使用预定义变量的例子：

yaml

---
title: Docs with VitePress
editLink: true
---

# {{ $frontmatter.title }}

Guide content

frontmatter 数据可以通过特殊的 $frontmatter 全局变量来访问：

还可以使用 useData() 辅助函数在 <script setup> 中访问当前页面的 frontmatter。

其他 frontmatter 格式

VitePress 也支持 JSON 格式的 frontmatter，以花括号开始和结束：

yaml

---
{
  "title": "Blogging Like a Hacker",
  "editLink": true
}
---

预定义变量

基本示例

包含语言/标题/自定义标题/站点描述

yaml

---
lang: zh-CN
title: VitePress
titleTemplate: Vite 和 Vue 强力驱动的静态网站生成器
description: 简单、强大、快速。满足你一直想要的现代SSG框架
---

head

Type: array
Default: undefined
类型：HeadConfig[]

指定要为当前页面注入的额外 head 标签。将附加在站点级配置注入的头部标签之后。

定义额外的需要注入的head标签。

yaml

---
head:
  - - meta
    - name: description
      content: hello
  - - meta
    - name: keywords
      content: super duper SEO
---

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

title

Type: string
Default: h1_title || siteData.title

页面的标题。它与 config.title 相同，并且覆盖站点级配置。

yaml

---
title: VitePress
---

titleTemplate

类型：string | boolean

标题的后缀。它与 config.titleTemplate 相同，它会覆盖站点级别的配置。

yaml

---
title: VitePress
titleTemplate: Vite & Vue powered static site generator
---

description

类型：string

页面的描述。它与 config.description 相同，它会覆盖站点级别的配置。

yaml

---
description: VitePress
---

仅默认主题

以下 frontmatter 选项仅在使用默认主题时适用。

所谓的默认主题，也就是config.js配置文件中指定的，如下所示：

import { defineConfig } from 'vitepress'

export default defineConfig({
})

首页布局模式-layout

类型：doc | home | page
默认值：doc

指定页面的布局。

doc——它将默认文档样式应用于 markdown 内容。
home——“主页”的特殊布局。可以添加额外的选项，例如 hero 和 features，以快速创建漂亮的落地页。
page——表现类似于 doc，但它不对内容应用任何样式。当想创建一个完全自定义的页面时很有用。

yaml

---
layout: doc
---

hero

home page only

当 layout 设置为 home 时，定义主页 hero 部分的内容，也就是我们网站的居中文案，都比较简单。

关于actions

theme: brand 为主要的按钮，还有 alt sponsor

text: 开始 文字可以自定义

link: /getting-started 跳转的路径

yaml

---
hero:
  name: VitePress
  text: "快速上手中文教程"
  tagline: 如果你也想搭建它，那跟我一起做吧
  image:
    src: /logo.png
    alt: VitePress
  actions:
    - theme: brand
      text: 开始
      link: /getting-started
    - theme: alt
      text: GitHub
      link: https://github.com/vuejs/vitepress
---

hero的文字及图片，也可以添加渐变色

警告

代码必须用 <style> 标签包裹

css

<style>
  :root {
  /* 标题渐变色 */
  --vp-home-hero-name-color: transparent;
  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);

  /*图标背景渐变色 */
  --vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);
  --vp-home-hero-image-filter: blur(40px);
}
</style>

如果你想单独改按钮，就这样配置

css

<style>
  :root {
  /* brand按钮 */
  --vp-button-brand-border: #F6CEEC;
  --vp-button-brand-text: #F6CEEC;
  --vp-button-brand-bg: #D939CD;

  --vp-button-brand-hover-border: #F6CEEC;
  --vp-button-brand-hover-text: #fff;
  --vp-button-brand-hover-bg: #D939CD;

  --vp-button-brand-active-border: #F6CEEC;
}
</style>

说明

其他美化方案请点我查看

features

home page only

定义当layout 设置为 home 时要在 features 部分中显示的项目。

特性可以使用emoji表情、图片以及SVG创建图形

信息

Emoji：https://emojixd.com/
图片：直接引用，也可以使用明暗色图区别开
SVG图形：<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32">这里是path开头的图形元素</svg>

yaml

---
features:
  - icon: 📝
    title: 专注于您的内容
    details: 只需使用 Markdown 即可轻松创建精美的文档网站
  - icon: 
      dark: /logo.png
      light: /logo-light.png
    title: 享受Vite DX
    details: Instant server start, lightning fast hot updates, and leverage Vite ecosystem plugins.
  - icon: <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6 3.22-5.6Z"/><path fill="#41b883" d="m2 3.925 14 24.15 14-24.15h-5.6L16 18.415 7.53 3.925Z"/><path fill="#35495e" d="M7.53 3.925 16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"/></svg>
    title: 使用 Vue 进行定制
    details: 直接在 Markdown 中使用 Vue 语法和组件，或使用 Vue 构建自定义主题
  - icon: 🚀
    title: 快速发布网站
    details: 使用静态 HTML 进行快速初始加载，使用客户端路由进行快速加载后导航
---

如果你想做跳转也是可以的，我们添加一个 link 和 linkText

yaml

---
features:
  - icon: 📝
    title: 专注于您的内容
    details: 只需使用 Markdown 即可轻松创建精美的文档网站
  - icon: 
      dark: /logo.png
      light: /logo-light.png
    title: 享受Vite DX
    details: Instant server start, lightning fast hot updates, and leverage Vite ecosystem plugins.
    link: https://vitejs.cn/
    linkText: Vite
  - icon: <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6 3.22-5.6Z"/><path fill="#41b883" d="m2 3.925 14 24.15 14-24.15h-5.6L16 18.415 7.53 3.925Z"/><path fill="#35495e" d="M7.53 3.925 16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"/></svg>
    title: 使用 Vue 进行定制
    details: 直接在 Markdown 中使用 Vue 语法和组件，或使用 Vue 构建自定义主题
  - icon: 🚀
    title: 快速发布网站
    details: 使用静态 HTML 进行快速初始加载，使用客户端路由进行快速加载后导航
---

类型：boolean
默认值：true

是否显示导航栏。

你可以通过在特定的页面上设置navbar:false来禁用导航。

yaml

---
navbar: false
---

类型：boolean
默认值：true

是否显示侧边栏.

也可以通过在特定的页面上设置navbar:false来禁用侧边栏。

yaml

---
sidebar: false
---

大纲

aside

类型：boolean | left
默认值：true

侧边大纲默认在右侧，通过 aside 设置左侧或关闭，默认 true

定义大纲在 doc 布局中的位置。

false：禁用大纲
true：启用大纲，并位于右侧
left：启用大纲，并位于左侧

yaml

---
aside: false
---

outline

类型：number | [number, number] | 'deep' | false
默认值：2
设置到六级标题可以用 'deep' ，关闭 false

大纲中显示的标题级别。它与 config.themeConfig.outline.level 相同，它会覆盖站点级的配置。

yaml

---
outline: [2,3]
---

想要当前页不显示大纲，则：

yaml

---
outline: false
---

lastUpdated

类型：boolean | Date
默认值：true

是否在当前页面的页脚中显示最后更新时间的文本。如果指定了日期时间，则会显示该日期时间而不是上次 git 修改的时间戳。

yaml

---
lastUpdated: false
---

editLink

类型：boolean
默认值：true

是否在当前页的页脚显示编辑链接。

yaml

---
editLink: false
---

上下页

默认从侧边栏配置中读取，也可以指定在上/下页显示的文本/链接

更改显示的文字

仅更改上/下页显示的文字，跳转还是按照侧边栏配置的读取的

yaml

---
prev: '页面 | 更详细的页面配置'
next: 'Markdown | 更详细的markdown'
---

更改跳转链接

可更改成任意自己想跳转的文章

yaml

---
prev:
  text: '页面'
  link: '/page'
next:
  text: 'Markdown'
  link: '/markdown'
---

关闭上下页

yaml

---
prev: false
next: false
---

类型：boolean
默认值：true

是否显示页脚。

yaml

---
footer: false
---

pageClass

类型：string

在特定页面添加额外的类名

yaml

---
pageClass: custom-page-class
---

然后，你可以在特定页面中自定义样式，路径 .vitepress/theme/custom.css

css

.custom-page-class {
  /* 特定页面的样式 */
}

配置参考

以下配置参考来自：Frontmatter | VitePress (yiov.top)

点我查看配置参考

yaml

---
layout: home

hero:
  name: VitePress
  text: "快速上手中文教程"
  tagline: 如果你也想搭建它，那跟我一起做吧
  image:
    src: /logo.png
    alt: VitePress
  actions:
    - theme: brand
      text: 开始
      link: /getting-started
    - theme: alt
      text: GitHub
      link: https://github.com/vuejs/vitepress
    - theme: sponsor
      text: 视频介绍
      link: 
    - theme: sponsor
      text: 相关资料
      link: 

features:
  - icon: 📝
    title: 专注于您的内容
    details: 只需使用 Markdown 即可轻松创建精美的文档网站
  - icon: 
      dark: /vitepress.png
      light: /vitepress-light.png
    title: 享受Vite DX
    details: 即时服务器启动，闪电般快速的热更新，并利用 Vite 生态插件
    link: https://vitejs.cn/
    linkText: Vite
  - icon: <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6 3.22-5.6Z"/><path fill="#41b883" d="m2 3.925 14 24.15 14-24.15h-5.6L16 18.415 7.53 3.925Z"/><path fill="#35495e" d="M7.53 3.925 16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"/></svg>
    title: 使用 Vue 进行定制
    details: 直接在 Markdown 中使用 Vue 语法和组件，或使用 Vue 构建自定义主题
  - icon: 🚀
    title: 快速发布网站
    details: 使用静态 HTML 进行快速初始加载，使用客户端路由进行快速加载后导航
---

关于frontmatter ​

frontmatter的示例 ​

访问 frontmatter 数据 ​

其他 frontmatter 格式 ​

预定义变量 ​

基本示例 ​

head ​

title ​

titleTemplate ​

description ​

仅默认主题 ​

首页布局模式-layout ​

hero ​

features ​

navbar ​

sidebar ​

大纲 ​

aside ​

outline ​

lastUpdated ​

editLink ​

上下页 ​

footer ​

pageClass ​

配置参考 ​

关于frontmatter

frontmatter的示例

访问 frontmatter 数据

其他 frontmatter 格式

预定义变量

基本示例

head

title

titleTemplate

description

仅默认主题

首页布局模式-layout

hero

features

navbar

sidebar

大纲

aside

outline

lastUpdated

editLink

上下页

footer

pageClass

配置参考