Any Markdown file that contains a YAML frontmatter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file, and must take the form of valid YAML set between triple-dashed lines. Example:
## Usage
VitePress supports YAML frontmatter in all Markdown files, parsing them with [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file (before any elements including `<script>` tags), and must take the form of valid YAML set between triple-dashed lines. Example:
```md
```md
---
---
@ -11,7 +13,11 @@ editLink: true
Many site or default theme config options have corresponding options in frontmatter. You can use frontmatter to override specific behavior for the current page only. For details, see [Frontmatter Config Reference](/reference/frontmatter-config).
Many site or default theme config options have corresponding options in frontmatter. You can use frontmatter to override specific behavior for the current page only. For details, see [Frontmatter Config Reference](/reference/frontmatter-config).
You can also define custom frontmatter data of your own, to be used in dynamic Vue expressions on the page. Frontmatter data can be accessed via the special `$frontmatter` global variable:
You can also define custom frontmatter data of your own, to be used in dynamic Vue expressions on the page.
## Accessing Frontmatter Data
Frontmatter data can be accessed via the special `$frontmatter` global variable:
Here's an example of how you could use it in your Markdown file:
Here's an example of how you could use it in your Markdown file:
@ -26,6 +32,8 @@ editLink: true
Guide content
Guide content
```
```
You can also access current page's frontmatter data in `<script setup>` with the [`useData()`](/reference/runtime-api#usedata) helper.
## Alternative Frontmatter Formats
## Alternative Frontmatter Formats
VitePress also supports JSON frontmatter syntax, starting and ending in curly braces:
VitePress also supports JSON frontmatter syntax, starting and ending in curly braces:
The configuration for the sidebar menu item. You may learn more details at [Theme: Sidebar](./default-theme-sidebar).
The configuration for the sidebar menu item. More details in [Default Theme: Sidebar](./default-theme-sidebar).
```js
```js
export default {
export default {
@ -271,7 +271,7 @@ export interface Footer {
- Type: `EditLink`
- Type: `EditLink`
Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Theme: Edit Link](./default-theme-edit-link) for more details.
Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Default Theme: Edit Link](./default-theme-edit-link) for more details.
```js
```js
export default {
export default {
@ -310,7 +310,7 @@ export default {
- Type: `AlgoliaSearch`
- Type: `AlgoliaSearch`
An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Theme: Search](./default-theme-search)
An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Default Theme: Search](./default-theme-search)
@ -31,7 +31,7 @@ Note that even in this layout, sidebar will still show up if the page has a matc
## Home Layout
## Home Layout
Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](/reference/default-theme-home-page) for more details.
Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Default Theme: Home Page](/reference/default-theme-home-page) for more details.
Frontmatter enables page based configuration. In every markdown file, you can use frontmatter config to override app-level or theme config options. Also, there are config options which you can only define in frontmatter.
Frontmatter enables page based configuration. In every markdown file, you can use frontmatter config to override site-level or theme-level config options. Also, there are config options which you can only define in frontmatter.
```yaml
Example usage:
```md
---
---
title: Docs with VitePress
title: Docs with VitePress
editLink: true
editLink: true
---
---
```
```
You can access frontmatter by `$frontmatter` helper inside any markdown file.
You can access frontmatter data via the `$frontmatter` global in Vue expressions:
```md
```md
{{ $frontmatter.title }}
{{ $frontmatter.title }}
@ -19,7 +25,7 @@ You can access frontmatter by `$frontmatter` helper inside any markdown file.
- Type: `string`
- Type: `string`
Title for the page. It's same as [config.title](/reference/site-config#title), and it overrides the app config.
Title for the page. It's same as [config.title](/reference/site-config#title), and it overrides the site-level config.
```yaml
```yaml
---
---
@ -31,7 +37,7 @@ title: VitePress
- Type: `string | boolean`
- Type: `string | boolean`
The suffix for the title. It's same as [config.titleTemplate](/reference/site-config#titletemplate), and it overrides the app config.
The suffix for the title. It's same as [config.titleTemplate](/reference/site-config#titletemplate), and it overrides the site-level config.
```yaml
```yaml
---
---
@ -44,7 +50,7 @@ titleTemplate: Vite & Vue powered static site generator
- Type: `string`
- Type: `string`
Description for the page. It's same as [config.description](/reference/site-config#description), and it overrides the app config.
Description for the page. It's same as [config.description](/reference/site-config#description), and it overrides the site-level config.
```yaml
```yaml
---
---
@ -56,7 +62,7 @@ description: VitePress
- Type: `HeadConfig[]`
- Type: `HeadConfig[]`
Specify extra head tags to be injected:
Specify extra head tags to be injected for the current page. Will be appended after head tags injected by site-level config.
```yaml
```yaml
---
---
@ -76,20 +82,11 @@ type HeadConfig =
| [string, Record<string,string>, string]
| [string, Record<string,string>, string]
```
```
## lastUpdated
## Default Theme Only
- Type: `boolean`
The following frontmatter options are only applicable when using the default theme.
- Default: `true`
Whether to display [Last Updated](/reference/default-theme-last-updated) text in the current page.
This option only takes effect when `layout` is set to `home`.
It defines contents of home hero section.
```yaml
---
layout: home
hero:
name: VitePress
text: Vite & Vue powered static site generator.
tagline: Lorem ipsum...
actions:
- theme: brand
text: Get Started
link: /guide/what-is-vitepress
- theme: alt
text: View on GitHub
link: https://github.com/vuejs/vitepress
---
```
```ts
interface Hero {
// The string shown top of `text`. Comes with brand color
// and expected to be short, such as product name.
name?: string
// The main text for the hero section. This will be defined
// as `h1` tag.
text: string
// Tagline displayed below `text`.
tagline?: string
// Action buttons to display in home hero section.
actions?: HeroAction[]
}
interface HeroAction {
// Color theme of the button. Defaults to `brand`.
theme?: 'brand' | 'alt'
// Label of the button.
text: string
// Destination link of the button.
link: string
}
```
## features
- Type: `Feature[]`
This option only takes effect when `layout` is set to `home`.
Defines contents of home hero section when `layout` is set to `home`. More details in [Default Theme: Home Page](/reference/default-theme-home-page).
It defines items to display in features section.
### features <Badgetype="info"text="default theme only"/><Badgetype="info"text="Home page only"/>
You may learn more about it in [Theme: Home Page](/reference/default-theme-home-page).
Defines items to display in features section when `layout` is set to `home`. More details in [Default Theme: Home Page](/reference/default-theme-home-page).
The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](/reference/default-theme-config#outline), and it overrides the theme config.
The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](/reference/default-theme-config#outline), and it overrides the theme config.
Evan You
2 years ago