mirror of https://github.com/vuejs/vitepress
Xavi Lee
4 years ago
parent
f95361ea10
commit
422aba0f9a
@ -0,0 +1,192 @@
|
||||
# Frontmatter 配置 {#frontmatter-configs}
|
||||
|
||||
Frontmatter 支持基于页面的配置。在每个标签上，你可以自由地添加任何设置来覆盖任何全局应用或主题配置。此外，还有一些配置，你只能在 Frontmatter 中定义。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Docs with VitePress
|
||||
editLink: true
|
||||
---
|
||||
```
|
||||
|
||||
你可以通过 `$frontmatter` 在任何 markdown 文件中访问 frontmatter。
|
||||
|
||||
```md
|
||||
{{ $frontmatter.title }}
|
||||
```
|
||||
|
||||
## title
|
||||
|
||||
- Type: `string`
|
||||
|
||||
页面的标题。它与 [config.title](../config/app-configs#title) 相同，并覆盖了应用全局配置。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: VitePress
|
||||
---
|
||||
```
|
||||
|
||||
## titleTemplate
|
||||
|
||||
- Type: `string | boolean`
|
||||
|
||||
标题的后缀。它与 [config.titleTemplate](../config/app-configs#titletemplate) 相同，并覆盖了应用全局配置。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: VitePress
|
||||
titleTemplate: Vite & Vue powered static site generator
|
||||
---
|
||||
```
|
||||
|
||||
## description
|
||||
|
||||
- Type: `string`
|
||||
|
||||
页面的描述。它与 [config.description](../config/app-configs#description) 相同，并覆盖了应用全局配置。
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: VitePress
|
||||
---
|
||||
```
|
||||
|
||||
### head
|
||||
|
||||
- Type: `HeadConfig[]`
|
||||
|
||||
指定要注入的额外 head 标签。
|
||||
|
||||
```yaml
|
||||
---
|
||||
head:
|
||||
- - meta
|
||||
- name: description
|
||||
content: hello
|
||||
- - meta
|
||||
- name: keywords
|
||||
content: super duper SEO
|
||||
---
|
||||
```
|
||||
|
||||
```ts
|
||||
type HeadConfig =
|
||||
| [string, Record<string, string>]
|
||||
| [string, Record<string, string>, string]
|
||||
```
|
||||
|
||||
## lastUpdated
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `true`
|
||||
|
||||
在当前页面是否显示[最后更新](../guide/theme-last-updated)文本。
|
||||
|
||||
```yaml
|
||||
---
|
||||
lastUpdated: false
|
||||
---
|
||||
```
|
||||
|
||||
## layout
|
||||
|
||||
- Type: `doc | home | page`
|
||||
- Default: `doc`
|
||||
|
||||
决定页面的布局。
|
||||
|
||||
- `doc` - It applies default documentation styles to the markdown content.
|
||||
- `home` - Special layout for "Home Page". You may add extra options such as `hero` and `features` to rapidly create beautiful landing page.
|
||||
- `page` - Behave similar to `doc` but it applies no styles to the content. Useful when you want to create a fully custom page.
|
||||
|
||||
```yaml
|
||||
---
|
||||
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[]`
|
||||
|
||||
This option only takes effect when `layout` is set to `home`.
|
||||
|
||||
It defines items to display in features section.
|
||||
|
||||
You may learn more about it in [Theme: Home Page](../guide/theme-home-page).
|
||||
|
||||
## aside
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `true`
|
||||
|
||||
If you want the right aside component in `doc` layout not to be shown, set this option to `false`.
|
||||
|
||||
```yaml
|
||||
---
|
||||
aside: false
|
||||
---
|
||||
```
|
||||
|
||||
## outline
|
||||
|
||||
- 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](../config/theme-configs#outline), and it overrides the theme config.
|
||||
@ -0,0 +1,76 @@
|
||||
# 简介 {#introduction}
|
||||
|
||||
将配置文件放在 `.vitepress/config.js` 中。 这是放置所有 VitePress 特定文件的地方。
|
||||
|
||||
```
|
||||
.
|
||||
├─ docs
|
||||
│ ├─ .vitepress
|
||||
│ │ └─ config.js
|
||||
│ └─ index.md
|
||||
└─ package.json
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
你也可以使用任意的 `.ts`、`.cjs`、`.mjs`、`.cts` 和 `.mts` 作为配置文件的扩展名。
|
||||
:::
|
||||
|
||||
VitePress 带有 2 种类型的配置。一种是[应用全局配置](./app-configs)，它配置站点的基本功能，例如设置站点的标题，或自定义 Markdown 解析器的工作方式。其次是[主题配置](./theme-configs)，用于配置站点的主题，例如添加侧边栏，或者添加“在 GitHub 上编辑此页面”链接等功能。
|
||||
|
||||
你还可以在 [Frontmatter](./frontmatter-configs) 中进行另一种配置。Frontmatter 配置可以覆盖在该特定页面的应用全局配置或主题配置上定义的全局配置。但是，有几个选项也仅在 frontmatter 中可用。
|
||||
|
||||
请参阅相应的配置页面以了解更多信息。
|
||||
|
||||
## 配置智能提示 {#config-intellisense}
|
||||
|
||||
由于 VitePress 附带 TypeScript 类型，你可以利用 IDE 的智能提示和 jsdoc 类型提示：
|
||||
|
||||
```js
|
||||
/**
|
||||
* @type {import('vitepress').UserConfig}
|
||||
*/
|
||||
const config = {
|
||||
// ...
|
||||
}
|
||||
|
||||
export default config
|
||||
```
|
||||
|
||||
或者，你可以使用 `defineConfig` 辅助函数，它会提供智能提示，而无需 jsdoc 注释：
|
||||
|
||||
```js
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
VitePress 也直接支持 TS 配置文件。 你也可以将 `.vitepress/config.ts` 与 `defineConfig` 辅助函数一起使用。
|
||||
|
||||
## 主题配置类型 {#typed-theme-config}
|
||||
|
||||
默认情况下，`defineConfig` 辅助函数使用默认主题的主题配置类型：
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
// Type is `DefaultTheme.Config`
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
如果你使用自定义主题并希望对主题配置进行类型检查，则需要使用 `defineConfigWithTheme`，并通过通用参数传递自定义主题的配置类型：
|
||||
|
||||
```ts
|
||||
import { defineConfigWithTheme } from 'vitepress'
|
||||
import { ThemeConfig } from 'your-theme'
|
||||
|
||||
export default defineConfigWithTheme<ThemeConfig>({
|
||||
themeConfig: {
|
||||
// Type is `ThemeConfig`
|
||||
}
|
||||
})
|
||||
```
|
||||
@ -0,0 +1,316 @@
|
||||
# 主题配置 {#theme-configs}
|
||||
|
||||
主题配置可让你自定义主题。你可以通过将 `themeConfig` 键添加到配置文件来定义主题配置。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
lang: 'en-US',
|
||||
title: 'VitePress',
|
||||
description: 'Vite & Vue powered static site generator.',
|
||||
|
||||
// Theme related configurations.
|
||||
themeConfig: {
|
||||
logo: '/logo.svg',
|
||||
nav: [...],
|
||||
sidebar: { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这里描述了 VitePress 默认主题的设置。如果你使用的是其他人创建的自定义主题，这些设置可能没有任何效果，或者可能表现不同。
|
||||
|
||||
## logo
|
||||
|
||||
- 类型：`ThemeableImage`
|
||||
|
||||
显示在导航栏中的 logo 文件，位于站点标题之前。接受路径字符串或包含明亮或黑暗模式不同 logo 的对象。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
logo: '/logo.svg'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
type ThemeableImage =
|
||||
| string
|
||||
| { src: string; alt?: string }
|
||||
| { light: string; dark: string; alt?: string }
|
||||
```
|
||||
|
||||
## siteTitle
|
||||
|
||||
- 类型：`string | false`
|
||||
|
||||
你可以自定义此项以替换导航中的默认站点标题 (应用配置中的 `title`)。当设置为 `false` 时，导航中的标题将被禁用。这在当你的 `logo` 已经包含网站标题文本时很有用。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
siteTitle: 'Hello World'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## nav
|
||||
|
||||
- 类型：`NavItem`
|
||||
|
||||
导航菜单项的配置。你可以在[主题: 导航栏](../guide/theme-nav#navigation-links)中了解更多详情。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Guide', link: '/guide' },
|
||||
{
|
||||
text: 'Dropdown Menu',
|
||||
items: [
|
||||
{ text: 'Item A', link: '/item-1' },
|
||||
{ text: 'Item B', link: '/item-2' },
|
||||
{ text: 'Item C', link: '/item-3' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
type NavItem = NavItemWithLink | NavItemWithChildren
|
||||
|
||||
type NavItemWithLink = {
|
||||
text: string
|
||||
link: string
|
||||
activeMatch?: string
|
||||
}
|
||||
|
||||
interface NavItemWithChildren {
|
||||
text?: string
|
||||
items: NavItemWithLink[]
|
||||
activeMatch?: string
|
||||
}
|
||||
```
|
||||
|
||||
## sidebar
|
||||
|
||||
- 类型：`Sidebar`
|
||||
|
||||
侧边栏菜单项的配置。你可以在[主题: 侧边栏](../guide/theme-sidebar)了解更多详情。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Guide',
|
||||
items: [
|
||||
{ text: 'Introduction', link: '/introduction' },
|
||||
{ text: 'Getting Started', link: '/getting-started' },
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
type Sidebar = SidebarGroup[] | SidebarMulti
|
||||
|
||||
interface SidebarMulti {
|
||||
[path: string]: SidebarGroup[]
|
||||
}
|
||||
|
||||
interface SidebarGroup {
|
||||
text: string
|
||||
items: SidebarItem[]
|
||||
collapsible?: boolean
|
||||
collapsed?: boolean
|
||||
}
|
||||
|
||||
interface SidebarItem {
|
||||
text: string
|
||||
link: string
|
||||
}
|
||||
```
|
||||
|
||||
## outline
|
||||
|
||||
- 类型：`number | [number, number] | 'deep' | false`
|
||||
- 默认值：`2`
|
||||
|
||||
纲要中显示的标题的级别。你可以通过传递一个数字来指定一个特定的级别，也可以通过传递一个包含底限和上限的元组来提供一个级别范围。当传递等于 `[2, 6]` 的 `'deep'` 时，除了 `h1` 之外，所有的标题级别都显示在大纲中。可以设置 `false` 来隐藏轮廓。
|
||||
|
||||
## outlineTitle
|
||||
|
||||
- 类型：`string`
|
||||
- 默认值：`On this page`
|
||||
|
||||
可用于自定义右侧边栏的标题 (在大纲链接的顶部)。这在用另一种语言编写文档时很有用。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
outlineTitle: 'In hac pagina'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## socialLinks
|
||||
|
||||
- 类型：`SocialLink[]`
|
||||
|
||||
你可以定义此选项以在导航中展示带有图标的社交帐户链接。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' },
|
||||
{ icon: 'twitter', link: '...' },
|
||||
// You can also add custom icons by passing SVG as string:
|
||||
{
|
||||
icon: {
|
||||
svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
|
||||
},
|
||||
link: '...'
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
interface SocialLink {
|
||||
icon: SocialLinkIcon
|
||||
link: string
|
||||
}
|
||||
|
||||
type SocialLinkIcon =
|
||||
| 'discord'
|
||||
| 'facebook'
|
||||
| 'github'
|
||||
| 'instagram'
|
||||
| 'linkedin'
|
||||
| 'mastodon'
|
||||
| 'slack'
|
||||
| 'twitter'
|
||||
| 'youtube'
|
||||
| { svg: string }
|
||||
```
|
||||
|
||||
## footer
|
||||
|
||||
- 类型：`Footer`
|
||||
|
||||
页脚配置。你可以添加一些消息和版权内容。出于设计考虑，仅当页面不包含侧边栏时才会显示页脚。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
message: 'Released under the MIT License.',
|
||||
copyright: 'Copyright © 2019-present Evan You'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface Footer {
|
||||
message?: string
|
||||
copyright?: string
|
||||
}
|
||||
```
|
||||
|
||||
## editLink
|
||||
|
||||
- 类型：`EditLink`
|
||||
|
||||
编辑链接可让你显示链接以编辑 Git 管理服务 (例如 GitHub 或 GitLab上的页面)。有关详细信息，请参见[主题：编辑链接](../guide/theme-edit-link)。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
|
||||
text: 'Edit this page on GitHub'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface EditLink {
|
||||
pattern: string
|
||||
text?: string
|
||||
}
|
||||
```
|
||||
|
||||
## lastUpdatedText
|
||||
|
||||
- 类型：`string`
|
||||
- 默认值：`Last updated`
|
||||
|
||||
显示“上次更新时间”之前的前缀文本。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
lastUpdatedText: 'Updated Date'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## carbonAds
|
||||
|
||||
- 类型：`CarbonAds`
|
||||
|
||||
显示 [Carbon Ads](https://www.carbonads.net/) 的选项。
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
carbonAds: {
|
||||
code: 'your-carbon-code',
|
||||
placement: 'your-carbon-placement'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface CarbonAds {
|
||||
code: string
|
||||
placement: string
|
||||
}
|
||||
```
|
||||
|
||||
有关详细信息，请参见 [Theme: Carbon Ads](../guide/theme-carbon-ads)
|
||||
|
||||
## docFooter
|
||||
|
||||
- 类型：`DocFooter`
|
||||
|
||||
可用于自定义出现在上一个和下一个链接上方的文本。如果不是用英语编写文档，这很有帮助。
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
docFooter: {
|
||||
prev: 'Pagina prior',
|
||||
next: 'Proxima pagina'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface DocFooter {
|
||||
prev?: string
|
||||
next?: string
|
||||
}
|
||||
```
|
||||
Loading…
Reference in new issue