docs: revise frontmatter docs

vuejs · Mar 7, 2023 · fe07329 · fe07329
1 parent 7b58df3
commit fe07329
Show file tree

Hide file tree

Showing 4 changed files with 51 additions and 90 deletions.
diff --git a/docs/guide/frontmatter.md b/docs/guide/frontmatter.md
@@ -1,6 +1,8 @@
 # Frontmatter
 
-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
 ---
@@ -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).
 
-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:
 
@@ -26,6 +32,8 @@ editLink: true
 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
 
 VitePress also supports JSON frontmatter syntax, starting and ending in curly braces:

diff --git a/docs/reference/default-theme-config.md b/docs/reference/default-theme-config.md
@@ -64,7 +64,7 @@ export default {
 
 - Type: `NavItem`
 
-The configuration for the nav menu item. You may learn more details at [Theme: Nav](./default-theme-nav#navigation-links).
+The configuration for the nav menu item. More details in [Default Theme: Nav](./default-theme-nav#navigation-links).
 
 ```js
 export default {
@@ -111,7 +111,7 @@ interface NavItemWithChildren {
 
 - Type: `Sidebar`
 
-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
 export default {
@@ -271,7 +271,7 @@ export interface Footer {
 
 - 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
 export default {
@@ -310,7 +310,7 @@ export default {
 
 - 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)
 
 ```ts
 export interface AlgoliaSearchOptions extends DocSearchProps {
@@ -344,7 +344,7 @@ export interface CarbonAdsOptions {
 }
 ```
 
-Learn more in [Theme: Carbon Ads](./default-theme-carbon-ads)
+Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads)
 
 ## docFooter
 

diff --git a/docs/reference/default-theme-layout.md b/docs/reference/default-theme-layout.md
@@ -31,7 +31,7 @@ Note that even in this layout, sidebar will still show up if the page has a matc
 
 ## 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.
 
 ## No Layout
 

diff --git a/docs/reference/frontmatter-config.md b/docs/reference/frontmatter-config.md
@@ -1,15 +1,21 @@
+---
+outline: deep
+---
+
 # Frontmatter Config
 
-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
 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
 {{ $frontmatter.title }}
@@ -19,7 +25,7 @@ You can access frontmatter by `$frontmatter` helper inside any markdown file.
 
 - 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
 ---
@@ -31,7 +37,7 @@ title: VitePress
 
 - 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
 ---
@@ -44,7 +50,7 @@ titleTemplate: Vite & Vue powered static site generator
 
 - 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
 ---
@@ -56,7 +62,7 @@ description: VitePress
 
 - 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
 ---
@@ -76,20 +82,11 @@ type HeadConfig =
  | [string, Record<string, string>, string]
 ```
 
-## lastUpdated
+## Default Theme Only
 
-- Type: `boolean`
-- Default: `true`
-
-Whether to display [Last Updated](/reference/default-theme-last-updated) text in the current page.
-
-```yaml
----
-lastUpdated: false
----
-```
+The following frontmatter options are only applicable when using the default theme.
 
-## layout
+### layout <Badge type="info" text="default theme only" />
 
 - Type: `doc | home | page`
 - Default: `doc`
@@ -106,72 +103,15 @@ layout: doc
 ---
 ```
 
-## hero
-
-- Type: `Hero`
-
-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[]`
+### hero <Badge type="info" text="default theme only" /> <Badge type="info" text="Home page only" />
 
-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 <Badge type="info" text="default theme only" /> <Badge type="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).
 
-## aside
+### aside <Badge type="info" text="default theme only" />
 
 - Type: `boolean`
 - Default: `true`
@@ -184,9 +124,22 @@ aside: false
 ---
 ```
 
-## outline
+### outline <Badge type="info" text="default theme only" />
 
 - Type: `number | [number, number] | 'deep' | false`
 - Default: `2`
 
 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.
+
+### lastUpdated <Badge type="info" text="default theme only" />
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to display [Last Updated](/reference/default-theme-last-updated) text in the current page.
+
+```yaml
+---
+lastUpdated: false
+---
+```