Skip to content

Commit 8003425

Browse files
ulivzulivz
committed
docs: frontmatter
1 parent 249cd25 commit 8003425

File tree

5 files changed

+240
-72
lines changed

5 files changed

+240
-72
lines changed

‎packages/docs/docs/.vuepress/config.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ function getGuideSidebar (groupA, groupB) {
109109
title: groupB,
110110
collapsable: false,
111111
children: [
112+
'frontmatter',
112113
'permalinks',
113114
'markdown-slot'
114115
]

‎packages/docs/docs/guide/frontmatter.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Front Matter
2+
3+
Any markdown file that contains a YAML front matter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The front matter must be the first thing in the markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
4+
5+
```markdown
6+
---
7+
title: Blogging Like a Hacker
8+
lang: en-US
9+
---
10+
```
11+
12+
Between these triple-dashed lines, you can set predefined variables (see [below](#predefined-global-variables) for a reference), or even create custom ones of your own. These variables will then be available to you to access using <code>[$frontmatter](../miscellaneous/global-computed.md#frontmatter)</code> at the rest of the page, plus all custom and theming components.
13+
14+
::: tip
15+
Front matter variables are **optional** in VuePress.
16+
:::
17+
18+
## Alternative Front Matter Formats
19+
20+
In addition, VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) front matter.
21+
22+
JSON front matter needs to start and end in curly braces:
23+
24+
```
25+
---
26+
{
27+
"title": "Blogging Like a Hacker",
28+
"lang": "en-US"
29+
}
30+
---
31+
```
32+
33+
TOML front matter needs to be explicitly marked as TOML:
34+
35+
```
36+
---toml
37+
title = "Blogging Like a Hacker"
38+
lang = "en-US"
39+
---
40+
```
41+
42+
43+
## Predefined Variables
44+
45+
### title
46+
47+
- Type: `string`
48+
- Default: `h1_title || siteConfig.title`
49+
50+
Title of current page.
51+
52+
### lang
53+
54+
- Type: `string`
55+
- Default: `en-US`
56+
57+
Language of current page.
58+
59+
### description
60+
61+
- Type: `string`
62+
- Default: `siteConfig.description`
63+
64+
Description of current page.
65+
66+
### layout
67+
68+
- Type: `string`
69+
- Default: `Layout`
70+
71+
Set the layout component of the current page.
72+
73+
### permalink
74+
75+
- Type: `string`
76+
- Default: `siteConfig.permalink`
77+
78+
Refer to: [Permalinks](./permalinks.md).
79+
80+
### metaTitle
81+
82+
- Type: `string`
83+
- Default: <code>\`${page.title} | ${siteConfig.title}\`</code>
84+
85+
Override the default meta title.
86+
87+
### meta
88+
89+
- Type: `array`
90+
- Default: `undefined`
91+
92+
Specify extra meta tags to be injected:
93+
94+
``` yaml
95+
---
96+
meta:
97+
- name: description
98+
content: hello
99+
- name: keywords
100+
content: super duper SEO
101+
---
102+
```
103+
104+
## Predefined Variables Powered By Default Theme
105+
106+
### navbar
107+
108+
- Type: `boolean`
109+
- Default: `undefined`
110+
111+
See: [Default Theme Config > Disable the Navbar](../theme/default-theme-config.md#disable-the-navbar).
112+
113+
### sidebar
114+
115+
- Type: `boolean|'auto'`
116+
- Default: `undefined`
117+
118+
See: [Default Theme Config > Sidebar](../theme/default-theme-config.md#sidebar).

‎packages/docs/docs/guide/markdown.md

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -66,43 +66,9 @@ lang: en-US
6666
---
6767
```
6868

69-
The data will be available to the rest of the page, plus all custom and theming components as `$page`.
69+
The data will be available to the rest of the page, plus all custom and theming components.
7070

71-
`title` and `lang` will be automatically set on the current page. In addition you can specify extra meta tags to be injected:
72-
73-
``` yaml
74-
---
75-
meta:
76-
- name: description
77-
content: hello
78-
- name: keywords
79-
content: super duper SEO
80-
---
81-
```
82-
83-
### Alternative Front Matter Formats
84-
85-
In addition, VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) front matter.
86-
87-
JSON front matter needs to start and end in curly braces:
88-
89-
```
90-
---
91-
{
92-
"title": "Blogging Like a Hacker",
93-
"lang": "en-US"
94-
}
95-
---
96-
```
97-
98-
TOML front matter needs to be explicitly marked as TOML:
99-
100-
```
101-
---toml
102-
title = "Blogging Like a Hacker"
103-
lang = "en-US"
104-
---
105-
```
71+
For detailed introduction, please move to [Front Matter](./frontmatter.md).
10672

10773
## GitHub-Style Tables
10874

‎packages/docs/docs/zh/guide/frontmatter.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Front Matter
2+
3+
任何包含 YAML front matter 的 Markdown 文件都将由 [gray-matter](https://github.com/jonschlinkert/gray-matter) 处理。front matter 必须是 markdown 文件中的第一部分，并且必须采用在三点划线之间书写的有效的 YAML。 这是一个基本的例子：
4+
5+
```markdown
6+
---
7+
title: Blogging Like a Hacker
8+
lang: en-US
9+
---
10+
```
11+
12+
在这些三条虚线之间，你可以设置预定义变量（参见[下面](#预定义变量)），甚至可以创建自己的自定义变量。 然后，您可以使用 <code> [$frontmatter](../miscellaneous/global-computed.md#frontmatter)</code> 在页面的其余部分、以及所有的自定义和主题组件访问这些变量。
13+
14+
::: tip
15+
在 VuePress 中，Front matter 是 **可选的**。
16+
:::
17+
18+
## 其他格式的 Front Matter
19+
20+
除了 YAML 之外，VuePress 也支持 JSON 或者 [TOML](https://github.com/toml-lang/toml) 格式的 front matter。
21+
22+
JSON front matter 需要以花括号开头和结尾：
23+
24+
```
25+
---
26+
{
27+
"title": "Blogging Like a Hacker",
28+
"lang": "en-US"
29+
}
30+
---
31+
```
32+
33+
TOML front matter 需要显式地标注为 TOML：
34+
35+
```
36+
---toml
37+
title = "Blogging Like a Hacker"
38+
lang = "en-US"
39+
---
40+
```
41+
42+
## 预定义变量
43+
44+
### title
45+
46+
- 类型: `string`
47+
- 默认值: `h1_title || siteConfig.title`
48+
49+
当前页面的标题。
50+
51+
### lang
52+
53+
- 类型: `string`
54+
- 默认值: `en-US`
55+
56+
当前页面的语言。
57+
58+
### description
59+
60+
- 类型: `string`
61+
- 默认值: `siteConfig.description`
62+
63+
当前页面的描述。
64+
65+
### layout
66+
67+
- 类型: `string`
68+
- 默认值: `Layout`
69+
70+
设置当前页面的布局组件。
71+
72+
### permalink
73+
74+
- 类型: `string`
75+
- 默认值: `siteConfig.permalink`
76+
77+
参考: [Permalinks](./permalinks.md).
78+
79+
### metaTitle
80+
81+
- 类型: `string`
82+
- 默认值: <code>\`${page.title} | ${siteConfig.title}\`</code>
83+
84+
重写默认的 meta title。
85+
86+
### meta
87+
88+
- 类型: `array`
89+
- 默认值: `undefined`
90+
91+
指定额外的要注入的 meta 标签：
92+
93+
``` yaml
94+
---
95+
meta:
96+
- name: description
97+
content: hello
98+
- name: keywords
99+
content: super duper SEO
100+
---
101+
```
102+
103+
## 默认主题的预定义变量
104+
105+
### navbar
106+
107+
- 类型: `boolean`
108+
- 默认值: `undefined`
109+
110+
参考: [默认值 Theme Config > Disable the Navbar](../theme/默认值-theme-config.md#禁用导航栏).
111+
112+
### sidebar
113+
114+
- 类型: `boolean|'auto'`
115+
- 默认值: `undefined`
116+
117+
参考: [默认值 Theme Config > Sidebar](../theme/默认值-theme-config.md#侧边栏).

‎packages/docs/docs/zh/guide/markdown.md

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -66,43 +66,9 @@ lang: en-US
6666
---
6767
```
6868

69-
这些数据可以在当前页的正文中使用，在任意的自定义或主题组件中，它可以通过 `$page` 来访问。
69+
这些数据可以在当前 markdown 的正文，或者是任意的自定义或主题组件中使用。
7070

71-
`title` 和 `lang` 的 meta 将会被自动地注入到当前的页面中，当然你也可以指定一些额外需要注入的 meta：
72-
73-
``` yaml
74-
---
75-
meta:
76-
- name: description
77-
content: hello
78-
- name: keywords
79-
content: super duper SEO
80-
---
81-
```
82-
83-
### 其他格式的 Front Matter
84-
85-
除了 YAML 之外，VuePress 也支持 JSON 或者 [TOML](https://github.com/toml-lang/toml) 格式的 front matter。
86-
87-
JSON front matter 需要以花括号开头和结尾：
88-
89-
```
90-
---
91-
{
92-
"title": "Blogging Like a Hacker",
93-
"lang": "en-US"
94-
}
95-
---
96-
```
97-
98-
TOML front matter 需要显式地标注为 TOML：
99-
100-
```
101-
---toml
102-
title = "Blogging Like a Hacker"
103-
lang = "en-US"
104-
---
105-
```
71+
想了解更多，请移步 [Front Matter](./frontmatter.md)。
10672

10773
## GitHub 风格的表格
10874

0 commit comments

Comments
 (0)