mirror of
https://github.com/WeBankFinTech/fes.js.git
synced 2025-04-06 03:59:53 +08:00
docs: 整理中文文档结构
This commit is contained in:
万纯
parent
d580e25bd0
commit
1bb4e40da5
@ -91,11 +91,12 @@ const config: UserConfig<DefaultThemeOptions> = {
|
|||||||
[
|
[
|
||||||
'@vuepress/plugin-docsearch',
|
'@vuepress/plugin-docsearch',
|
||||||
{
|
{
|
||||||
// TODO: create algolia index for vuepress-next
|
apiKey: '<API_KEY>',
|
||||||
// apiKey: '',
|
indexName: '<INDEX_NAME>',
|
||||||
// appId: '',
|
|
||||||
// indexName: '',
|
|
||||||
locales: {
|
locales: {
|
||||||
|
'/': {
|
||||||
|
placeholder: 'Search Documentation',
|
||||||
|
},
|
||||||
'/zh/': {
|
'/zh/': {
|
||||||
placeholder: '搜索文档',
|
placeholder: '搜索文档',
|
||||||
},
|
},
|
||||||
|
|||||||
@ -7,91 +7,32 @@ export const zh: NavbarConfig = [
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
text: '配置',
|
text: '配置',
|
||||||
link: '/zh/reference/config',
|
link: '/zh/reference/config/',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
text: 'API',
|
text: 'API',
|
||||||
link: '/zh/reference/api',
|
link: '/zh/reference/api/',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
text: '插件',
|
text: '插件',
|
||||||
link: '/zh/reference/plugin',
|
link: '/zh/reference/plugin/',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
text: 'CLI',
|
text: 'CLI',
|
||||||
link: '/zh/reference/cli',
|
link: '/zh/reference/cli/',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: '了解更多',
|
||||||
|
children: [
|
||||||
|
{
|
||||||
|
text: '更新日志',
|
||||||
|
link:
|
||||||
|
'https://github.com/WeBankFinTech/fes.js/blob/master/CHANGELOG.md',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'v1 文档',
|
||||||
|
link: 'https://webank.gitee.io/fes.js-v0/',
|
||||||
|
},
|
||||||
|
],
|
||||||
},
|
},
|
||||||
// {
|
|
||||||
// text: '参考',
|
|
||||||
// children: [
|
|
||||||
// {
|
|
||||||
// text: 'VuePress',
|
|
||||||
// children: [
|
|
||||||
// '/zh/reference/cli.md',
|
|
||||||
// '/zh/reference/config.md',
|
|
||||||
// '/zh/reference/frontmatter.md',
|
|
||||||
// '/zh/reference/components.md',
|
|
||||||
// '/zh/reference/plugin-api.md',
|
|
||||||
// '/zh/reference/theme-api.md',
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: '打包工具',
|
|
||||||
// children: [
|
|
||||||
// '/zh/reference/bundler/webpack.md',
|
|
||||||
// '/zh/reference/bundler/vite.md',
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: '默认主题',
|
|
||||||
// children: [
|
|
||||||
// '/zh/reference/default-theme/config.md',
|
|
||||||
// '/zh/reference/default-theme/frontmatter.md',
|
|
||||||
// '/zh/reference/default-theme/components.md',
|
|
||||||
// '/zh/reference/default-theme/markdown.md',
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: '官方插件',
|
|
||||||
// link: '/zh/reference/plugin/',
|
|
||||||
// children: [],
|
|
||||||
// },
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: '了解更多',
|
|
||||||
// children: [
|
|
||||||
// {
|
|
||||||
// text: '深入',
|
|
||||||
// children: [
|
|
||||||
// '/zh/guide/advanced/markdown.md',
|
|
||||||
// '/zh/guide/advanced/theme.md',
|
|
||||||
// '/zh/guide/advanced/plugin.md',
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: '其他资源',
|
|
||||||
// children: [
|
|
||||||
// '/zh/contributing.md',
|
|
||||||
// {
|
|
||||||
// text: '更新日志',
|
|
||||||
// link:
|
|
||||||
// 'https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md',
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: 'Awesome VuePress',
|
|
||||||
// link: 'https://github.com/vuepress/awesome-vuepress',
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: 'v1 文档',
|
|
||||||
// link: 'https://v1.vuepress.vuejs.org/zh/',
|
|
||||||
// },
|
|
||||||
// {
|
|
||||||
// text: 'v0 文档',
|
|
||||||
// link: 'https://v0.vuepress.vuejs.org/zh/',
|
|
||||||
// },
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
// ],
|
|
||||||
// },
|
|
||||||
]
|
]
|
||||||
|
|||||||
@ -4,87 +4,71 @@ export const zh: SidebarConfig = {
|
|||||||
'/zh/guide/': [
|
'/zh/guide/': [
|
||||||
{
|
{
|
||||||
isGroup: true,
|
isGroup: true,
|
||||||
text: '指南',
|
text: '介绍',
|
||||||
children: [
|
children: [
|
||||||
'/zh/guide/README.md',
|
'/zh/guide/README.md',
|
||||||
'/zh/guide/getting-started.md',
|
'/zh/guide/getting-started.md',
|
||||||
'/zh/guide/configuration.md',
|
|
||||||
'/zh/guide/page.md',
|
|
||||||
'/zh/guide/markdown.md',
|
|
||||||
'/zh/guide/assets.md',
|
|
||||||
'/zh/guide/i18n.md',
|
|
||||||
'/zh/guide/deployment.md',
|
|
||||||
'/zh/guide/theme.md',
|
|
||||||
'/zh/guide/plugin.md',
|
|
||||||
'/zh/guide/bundler.md',
|
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
],
|
|
||||||
'/zh/guide/advanced/': [
|
|
||||||
{
|
{
|
||||||
isGroup: true,
|
isGroup: true,
|
||||||
text: '深入',
|
text: '基础',
|
||||||
children: [
|
children: [
|
||||||
'/zh/guide/advanced/markdown.md',
|
]
|
||||||
'/zh/guide/advanced/theme.md',
|
|
||||||
'/zh/guide/advanced/plugin.md',
|
|
||||||
],
|
|
||||||
},
|
},
|
||||||
],
|
|
||||||
'/zh/reference/': [
|
|
||||||
{
|
{
|
||||||
isGroup: true,
|
isGroup: true,
|
||||||
text: 'VuePress 参考',
|
text: '进阶',
|
||||||
children: [
|
children: [
|
||||||
'/zh/reference/cli.md',
|
]
|
||||||
'/zh/reference/config.md',
|
|
||||||
'/zh/reference/frontmatter.md',
|
|
||||||
'/zh/reference/components.md',
|
|
||||||
'/zh/reference/plugin-api.md',
|
|
||||||
'/zh/reference/theme-api.md',
|
|
||||||
],
|
|
||||||
},
|
},
|
||||||
|
"/zh/guide/contributing.md",
|
||||||
|
"/zh/guide/faq.md"
|
||||||
],
|
],
|
||||||
'/zh/reference/bundler/': [
|
'/zh/reference/config/': [
|
||||||
{
|
'/zh/reference/config/README.md'
|
||||||
isGroup: true,
|
|
||||||
text: '打包工具参考',
|
|
||||||
children: [
|
|
||||||
'/zh/reference/bundler/webpack.md',
|
|
||||||
'/zh/reference/bundler/vite.md',
|
|
||||||
],
|
|
||||||
},
|
|
||||||
],
|
],
|
||||||
'/zh/reference/default-theme/': [
|
'/zh/reference/api/': [
|
||||||
{
|
'/zh/reference/api/README.md'
|
||||||
isGroup: true,
|
|
||||||
text: '默认主题参考',
|
|
||||||
children: [
|
|
||||||
'/zh/reference/default-theme/config.md',
|
|
||||||
'/zh/reference/default-theme/frontmatter.md',
|
|
||||||
'/zh/reference/default-theme/components.md',
|
|
||||||
'/zh/reference/default-theme/markdown.md',
|
|
||||||
],
|
|
||||||
},
|
|
||||||
],
|
],
|
||||||
'/zh/reference/plugin/': [
|
'/zh/reference/plugin/': [
|
||||||
{
|
{
|
||||||
isGroup: true,
|
isGroup: true,
|
||||||
text: '官方插件参考',
|
text: '指南',
|
||||||
children: [
|
children: [
|
||||||
'/zh/reference/plugin/active-header-links.md',
|
'/zh/reference/plugin/README.md',
|
||||||
'/zh/reference/plugin/back-to-top.md',
|
],
|
||||||
'/zh/reference/plugin/container.md',
|
},
|
||||||
'/zh/reference/plugin/debug.md',
|
{
|
||||||
'/zh/reference/plugin/docsearch.md',
|
isGroup: true,
|
||||||
'/zh/reference/plugin/git.md',
|
text: 'Presets',
|
||||||
'/zh/reference/plugin/google-analytics.md',
|
children: [
|
||||||
'/zh/reference/plugin/medium-zoom.md',
|
],
|
||||||
'/zh/reference/plugin/nprogress.md',
|
},
|
||||||
'/zh/reference/plugin/palette-stylus.md',
|
{
|
||||||
'/zh/reference/plugin/pwa.md',
|
isGroup: true,
|
||||||
'/zh/reference/plugin/pwa-popup.md',
|
text: 'Plugins',
|
||||||
|
children: [
|
||||||
|
'/zh/reference/plugin/plugins/access.md',
|
||||||
|
'/zh/reference/plugin/plugins/enums.md',
|
||||||
|
'/zh/reference/plugin/plugins/icon.md',
|
||||||
|
'/zh/reference/plugin/plugins/jest.md',
|
||||||
|
'/zh/reference/plugin/plugins/layout.md',
|
||||||
|
'/zh/reference/plugin/plugins/locale.md',
|
||||||
|
'/zh/reference/plugin/plugins/model.md',
|
||||||
|
'/zh/reference/plugin/plugins/request.md',
|
||||||
|
'/zh/reference/plugin/plugins/vuex.md',
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
isGroup: true,
|
||||||
|
text: '插件开发',
|
||||||
|
children: [
|
||||||
|
'/zh/reference/plugin/api.md'
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
|
'/zh/reference/cli/': [
|
||||||
|
'/zh/reference/cli/README.md',
|
||||||
|
],
|
||||||
}
|
}
|
||||||
|
|||||||
@ -1,102 +0,0 @@
|
|||||||
# Markdown 与 Vue SFC
|
|
||||||
|
|
||||||
每一个 Markdown 文件，首先都会编译为 HTML ，然后转换为一个 Vue 单文件组件 (SFC) 。换句话说，你可以把 Markdown 作为 Vue SFC 来看待：
|
|
||||||
|
|
||||||
- `<script>` 和 `<style>` 标签会直接被当作 Vue SFC 中的标签。换句话说，它们是从 `<template>` 标签中提升到了 SFC 的顶层。
|
|
||||||
- 所有 `<script>` 和 `<style>` 标签的以外的内容，会先被编译为 HTML ，然后被当作 Vue SFC 的 `<template>` 标签。
|
|
||||||
|
|
||||||
我们来看一个例子：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```vue
|
|
||||||
_你好， {{ msg }}_
|
|
||||||
|
|
||||||
<RedDiv>
|
|
||||||
|
|
||||||
_当前计数为： {{ count }}_
|
|
||||||
|
|
||||||
</RedDiv>
|
|
||||||
|
|
||||||
<button @click="count++">点我！</button>
|
|
||||||
|
|
||||||
<script>
|
|
||||||
import { h, ref } from 'vue'
|
|
||||||
|
|
||||||
const RedDiv = (_, ctx) => h(
|
|
||||||
'div',
|
|
||||||
{
|
|
||||||
class: 'red-div',
|
|
||||||
},
|
|
||||||
ctx.slots.default()
|
|
||||||
)
|
|
||||||
|
|
||||||
export default {
|
|
||||||
components: {
|
|
||||||
RedDiv,
|
|
||||||
},
|
|
||||||
|
|
||||||
setup() {
|
|
||||||
const msg = 'Markdown 中的 Vue'
|
|
||||||
const count = ref(0)
|
|
||||||
|
|
||||||
return {
|
|
||||||
msg,
|
|
||||||
count,
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
</script>
|
|
||||||
|
|
||||||
<style>
|
|
||||||
.red-div {
|
|
||||||
color: red;
|
|
||||||
}
|
|
||||||
</style>
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
_你好， {{ msg }}_
|
|
||||||
|
|
||||||
<RedDiv>
|
|
||||||
|
|
||||||
_当前计数为： {{ count }}_
|
|
||||||
|
|
||||||
</RedDiv>
|
|
||||||
|
|
||||||
<button @click="count++">点我！</button>
|
|
||||||
|
|
||||||
<script>
|
|
||||||
import { h, ref } from 'vue'
|
|
||||||
|
|
||||||
const RedDiv = (_, ctx) => h(
|
|
||||||
'div',
|
|
||||||
{
|
|
||||||
class: 'red-div',
|
|
||||||
},
|
|
||||||
ctx.slots.default()
|
|
||||||
)
|
|
||||||
|
|
||||||
export default {
|
|
||||||
components: {
|
|
||||||
RedDiv,
|
|
||||||
},
|
|
||||||
|
|
||||||
setup() {
|
|
||||||
const msg = 'Markdown 中的 Vue'
|
|
||||||
const count = ref(0)
|
|
||||||
|
|
||||||
return {
|
|
||||||
msg,
|
|
||||||
count,
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
</script>
|
|
||||||
|
|
||||||
<style>
|
|
||||||
.red-div {
|
|
||||||
color: red;
|
|
||||||
}
|
|
||||||
</style>
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# 开发插件
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# 开发主题
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,104 +0,0 @@
|
|||||||
# 静态资源
|
|
||||||
|
|
||||||
## 相对路径
|
|
||||||
|
|
||||||
你可以在你的 Markdown 内容中使用相对路径来引用静态资源：
|
|
||||||
|
|
||||||
```md
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
一般情况下，我们推荐你使用这种方式来引用图片，因为人们通常会把图片放在引用它的 Markdown 文件附近。
|
|
||||||
|
|
||||||
## Public 文件
|
|
||||||
|
|
||||||
你可以把一些静态资源放在 Public 目录中，它们会被复制到最终生成的网站的根目录下。
|
|
||||||
|
|
||||||
默认的 Public 目录是 `.vuepress/public` ，可以通过配置来修改。
|
|
||||||
|
|
||||||
在下列这些情况中，你可能会用到它：
|
|
||||||
|
|
||||||
- 你可能需要提供一些静态资源，但是它们并不直接被你的 Markdown 文件引用，比如 favicon 和 PWA 图标。
|
|
||||||
- 你可能想要托管一些共享的静态资源，甚至可能需要在你的网站外部引用它，比如 Logo 图片。
|
|
||||||
- 你可能想在你的 Markdown 内容中通过绝对路径来引入图片。
|
|
||||||
|
|
||||||
以我们文档的源文件为例，我们把 VuePress 的 Logo 放在了 Public 目录下：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
└─ docs
|
|
||||||
├─ .vuepress
|
|
||||||
| └─ public
|
|
||||||
| └─ hero.png # <- Logo 文件
|
|
||||||
└─ guide
|
|
||||||
└─ assets.md # <- 我们在这里
|
|
||||||
```
|
|
||||||
|
|
||||||
我们可以这样在当前页面引用 Logo ：
|
|
||||||
|
|
||||||
**Input**
|
|
||||||
|
|
||||||
```md
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
**Output**
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
配置参考： [public](../reference/config.md#public)
|
|
||||||
:::
|
|
||||||
|
|
||||||
### Base Helper
|
|
||||||
|
|
||||||
如果你的网站部署在非根路径下，即 [base](../reference/config.md#base) 不是 `"/"` ，你需要把 `base` 添加到 Public 文件的绝对路径前。
|
|
||||||
|
|
||||||
举例来说，如果你想要把网站部署到 `https://foo.github.io/bar/` ，那么应该把 `base` 设置为 `"/bar/"` ，此时你必须在 Markdown 文件中这样引用 Public 文件：
|
|
||||||
|
|
||||||
```md
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
显然，一旦某一天你修改了 `base`，这样的路径引用将会显得异常脆弱。这也是我们推荐你使用相对路径来引用静态文件的原因。
|
|
||||||
|
|
||||||
为了解决这个问题，VuePress 提供了内置的一个 Helper `$withBase` ，它可以帮助你生成正确的路径：
|
|
||||||
|
|
||||||
```md
|
|
||||||
<img :src="$withBase('/hero.png')" alt="VuePress Logo">
|
|
||||||
```
|
|
||||||
|
|
||||||
在 Markdown 中使用这个 Helper 会显得有些冗长，因此它可能对主题和插件作者更有帮助。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
配置参考： [base](../reference/config.md#base)
|
|
||||||
:::
|
|
||||||
|
|
||||||
## 依赖包和路径别名
|
|
||||||
|
|
||||||
尽管这不是常见用法，但是你可以从依赖包中引用图片：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install -D package-name
|
|
||||||
```
|
|
||||||
|
|
||||||
```md
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
在配置文件中设置的路径别名也同样支持：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
alias: {
|
|
||||||
'@alias': '/path/to/some/dir',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```md
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
配置参考： [alias](../reference/config.md#alias)
|
|
||||||
:::
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# 打包工具
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,84 +0,0 @@
|
|||||||
# 配置
|
|
||||||
|
|
||||||
## 配置文件
|
|
||||||
|
|
||||||
如果没有任何配置，你的 VuePress 站点仅有一些最基础的功能。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 `.vuepress` 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样：
|
|
||||||
|
|
||||||
```
|
|
||||||
├─ docs
|
|
||||||
│ ├─ .vuepress
|
|
||||||
│ │ └─ config.js
|
|
||||||
│ └─ README.md
|
|
||||||
├─ .gitignore
|
|
||||||
└─ package.json
|
|
||||||
```
|
|
||||||
|
|
||||||
VuePress 站点必要的配置文件是 `.vuepress/config.js`，它应该导出一个 JavaScript 对象。如果你使用 TypeScript ，你可以将其替换为 `.vuepress/config.ts` ，以便让 VuePress 配置得到更好的类型提示。
|
|
||||||
|
|
||||||
<CodeGroup>
|
|
||||||
<CodeGroupItem title="JS" active>
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
lang: 'zh-CN',
|
|
||||||
title: '你好， VuePress ！',
|
|
||||||
description: '这是我的第一个 VuePress 站点',
|
|
||||||
|
|
||||||
themeConfig: {
|
|
||||||
logo: 'https://vuejs.org/images/logo.png',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
</CodeGroupItem>
|
|
||||||
|
|
||||||
<CodeGroupItem title="TS">
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import type { UserConfig, DefaultThemeOptions } from 'vuepress'
|
|
||||||
|
|
||||||
const config: UserConfig<DefaultThemeOptions> = {
|
|
||||||
lang: 'zh-CN',
|
|
||||||
title: '你好， VuePress ！',
|
|
||||||
description: '这是我的第一个 VuePress 站点',
|
|
||||||
|
|
||||||
themeConfig: {
|
|
||||||
logo: 'https://vuejs.org/images/logo.png',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
|
|
||||||
export = config
|
|
||||||
```
|
|
||||||
|
|
||||||
</CodeGroupItem>
|
|
||||||
</CodeGroup>
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
我们接下来会把这个配置对象称为 **VuePress 配置**.
|
|
||||||
:::
|
|
||||||
|
|
||||||
## 配置作用域
|
|
||||||
|
|
||||||
你可能已经注意到了，在 VuePress 配置中有一项 `themeConfig` 配置项。
|
|
||||||
|
|
||||||
在 `themeConfig` 外部的配置项属于 **站点配置** ，而在 `themeConfig` 内部的配置项则属于 **主题配置**。
|
|
||||||
|
|
||||||
### 站点配置
|
|
||||||
|
|
||||||
站点配置的意思是，无论你使用什么主题，这些配置项都可以生效。
|
|
||||||
|
|
||||||
我们知道，每一个站点都应该有它的 `lang`, `title` 和 `description` 等属性，因此 VuePress 内置支持了这些属性的配置。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
前往 [配置参考](../reference/config.md) 查看所有站点配置。
|
|
||||||
:::
|
|
||||||
|
|
||||||
### 主题配置
|
|
||||||
|
|
||||||
主题配置将会被 VuePress 主题来处理，所以它取决于你使用的主题是什么。
|
|
||||||
|
|
||||||
如果你没有设置 VuePress 配置的 `theme` 配置项，则代表使用的是默认主题。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
前往 [默认主题 > 配置参考](../reference/default-theme/config.md) 查看默认主题的配置。
|
|
||||||
:::
|
|
||||||
@ -1,7 +1,3 @@
|
|||||||
---
|
|
||||||
sidebar: auto
|
|
||||||
---
|
|
||||||
|
|
||||||
# 贡献指南
|
# 贡献指南
|
||||||
|
|
||||||
## 概览
|
## 概览
|
||||||
@ -1,239 +0,0 @@
|
|||||||
# 部署
|
|
||||||
|
|
||||||
下述的指南基于以下条件：
|
|
||||||
|
|
||||||
- Markdown 源文件放置在你项目的 `docs` 目录；
|
|
||||||
- 使用的是默认的构建输出目录 (`.vuepress/dist`) ；
|
|
||||||
- 使用 [Yarn classic](https://classic.yarnpkg.com/zh-Hans/) 作为包管理器，当然也可以使用 NPM 。
|
|
||||||
- VuePress 作为项目依赖安装，并在 `package.json` 中配置了如下脚本：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"scripts": {
|
|
||||||
"docs:build": "vuepress build docs"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## GitHub Pages
|
|
||||||
|
|
||||||
1. 设置正确的 [base](../reference/config.md#base) 选项。
|
|
||||||
|
|
||||||
如果你准备发布到 `https://<USERNAME>.github.io/` ，你可以省略这一步，因为 `base` 默认就是 `"/"` 。
|
|
||||||
|
|
||||||
如果你准备发布到 `https://<USERNAME>.github.io/<REPO>/` ，也就是说你的仓库地址是 `https://github.com/<USERNAME>/<REPO>` ，则将 `base` 设置为 `"/<REPO>/"`。
|
|
||||||
|
|
||||||
2. 选项你想要使用的 CI 工具。这里我们以 [GitHub Actions](https://github.com/features/actions) 为例。
|
|
||||||
|
|
||||||
创建 `.github/workflows/docs.yml` 文件来配置工作流。
|
|
||||||
|
|
||||||
::: details 点击展开配置样例
|
|
||||||
```yaml
|
|
||||||
name: docs
|
|
||||||
|
|
||||||
on:
|
|
||||||
# 每当 push 到 main 分支时触发部署
|
|
||||||
push:
|
|
||||||
branches: [main]
|
|
||||||
# 手动触发部署
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
docs:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v2
|
|
||||||
with:
|
|
||||||
# “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
|
|
||||||
fetch-depth: 0
|
|
||||||
|
|
||||||
- name: Setup Node.js
|
|
||||||
uses: actions/setup-node@v1
|
|
||||||
with:
|
|
||||||
# 选择要使用的 node 版本
|
|
||||||
node-version: '14'
|
|
||||||
|
|
||||||
# 缓存 node_modules
|
|
||||||
- name: Cache dependencies
|
|
||||||
uses: actions/cache@v2
|
|
||||||
id: yarn-cache
|
|
||||||
with:
|
|
||||||
path: |
|
|
||||||
**/node_modules
|
|
||||||
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
|
|
||||||
restore-keys: |
|
|
||||||
${{ runner.os }}-yarn-
|
|
||||||
|
|
||||||
# 如果缓存没有命中，安装依赖
|
|
||||||
- name: Install dependencies
|
|
||||||
if: steps.yarn-cache.outputs.cache-hit != 'true'
|
|
||||||
run: yarn --frozen-lockfile
|
|
||||||
|
|
||||||
# 运行构建脚本
|
|
||||||
- name: Build VuePress site
|
|
||||||
run: yarn docs:build
|
|
||||||
|
|
||||||
# 查看 workflow 的文档来获取更多信息
|
|
||||||
# @see https://github.com/crazy-max/ghaction-github-pages
|
|
||||||
- name: Deploy to GitHub Pages
|
|
||||||
uses: crazy-max/ghaction-github-pages@v2
|
|
||||||
with:
|
|
||||||
# 部署到 gh-pages 分支
|
|
||||||
target_branch: gh-pages
|
|
||||||
# 部署目录为 VuePress 的默认输出目录
|
|
||||||
build_dir: docs/.vuepress/dist
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
请参考 [GitHub Pages 官方指南](https://pages.github.com/) 来获取更多信息。
|
|
||||||
:::
|
|
||||||
|
|
||||||
## GitLab Pages
|
|
||||||
|
|
||||||
1. 设置正确的 [base](../reference/config.md#base) 选项。
|
|
||||||
|
|
||||||
如果你准备发布到 `https://<USERNAME>.gitlab.io/` ，你可以省略这一步，因此 `base` 默认就是 `"/"` 。
|
|
||||||
|
|
||||||
如果你准备发布到 `https://<USERNAME>.gitlab.io/<REPO>/` ，也就是说你的仓库地址是 `https://gitlab.com/<USERNAME>/<REPO>` ，则将 `base` 设置为 `"/<REPO>/"`。
|
|
||||||
|
|
||||||
2. 创建 `.gitlab-ci.yml` 文件来配置 [GitLab CI](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) 工作流。
|
|
||||||
|
|
||||||
::: details 点击展开配置样例
|
|
||||||
```yaml
|
|
||||||
# 选择你要使用的 docker 镜像
|
|
||||||
image: node:14-buster
|
|
||||||
|
|
||||||
pages:
|
|
||||||
# 每当 push 到 main 分支时触发部署
|
|
||||||
only:
|
|
||||||
- main
|
|
||||||
|
|
||||||
# 缓存 node_modules
|
|
||||||
cache:
|
|
||||||
paths:
|
|
||||||
- node_modules/
|
|
||||||
|
|
||||||
# 安装依赖并运行构建脚本
|
|
||||||
script:
|
|
||||||
- yarn --frozen-lockfile
|
|
||||||
- yarn docs:build --dest public
|
|
||||||
|
|
||||||
artifacts:
|
|
||||||
paths:
|
|
||||||
- public
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
请参考 [GitLab Pages 官方指南](https://docs.gitlab.com/ce/user/project/pages/#getting-started) 来获取更多信息。
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Google Firebase
|
|
||||||
|
|
||||||
1. 请确保你已经安装了 [firebase-tools](https://www.npmjs.com/package/firebase-tools)。
|
|
||||||
|
|
||||||
2. 在你项目的根目录下创建 `firebase.json` 和 `.firebaserc`，并包含以下内容：
|
|
||||||
|
|
||||||
`firebase.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"hosting": {
|
|
||||||
"public": "./docs/.vuepress/dist",
|
|
||||||
"ignore": []
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`.firebaserc`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"projects": {
|
|
||||||
"default": "<YOUR_FIREBASE_ID>"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
3. 在执行了 `yarn docs:build` 或 `npm run docs:build` 后, 使用 `firebase deploy` 指令来部署。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
请参考 [Firebase CLI 官方指南](https://firebase.google.com/docs/cli) 来获取更多信息。
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Heroku
|
|
||||||
|
|
||||||
1. 首先安装 [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)；
|
|
||||||
|
|
||||||
2. [在这里](https://signup.heroku.com) 注册一个 Heroku 账号；
|
|
||||||
|
|
||||||
3. 运行 `heroku login` 并填写你的 Heroku 认证信息：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
heroku login
|
|
||||||
```
|
|
||||||
|
|
||||||
4. 在你的项目根目录中，创建一个名为 `static.json` 的文件，并包含下述内容：
|
|
||||||
|
|
||||||
`static.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"root": "./docs/.vuepress/dist"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
这里是你项目的配置，请参考 [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static) 来获取更多信息。
|
|
||||||
|
|
||||||
## Netlify
|
|
||||||
|
|
||||||
1. 前往 [Netlify](https://netlify.com) ，从 GitHub 创建一个新项目，并进行如下配置：
|
|
||||||
|
|
||||||
- **Build Command:** `yarn docs:build`
|
|
||||||
- **Publish directory:** `docs/.vuepress/dist`
|
|
||||||
|
|
||||||
2. 设置 [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) 来选择 Node 版本：
|
|
||||||
|
|
||||||
- `NODE_VERSION`: 14
|
|
||||||
|
|
||||||
3. 点击 deploy 按钮。
|
|
||||||
|
|
||||||
## Vercel
|
|
||||||
|
|
||||||
请查看 [Creating and Deploying a VuePress App with Vercel](https://vercel.com/guides/deploying-vuepress-to-vercel).
|
|
||||||
|
|
||||||
<!-- 下列平台是中文文档特有的，放在最下方 -->
|
|
||||||
|
|
||||||
## 云开发 CloudBase
|
|
||||||
|
|
||||||
[云开发 CloudBase](https://cloudbase.net/?site=vuepress) 是一个云原生一体化的 Serverless 云平台，支持静态网站、容器等多种托管能力，并提供简便的部署工具 [CloudBase Framework](https://cloudbase.net/framework.html?site=vuepress) 来一键部署应用。
|
|
||||||
|
|
||||||
1. 全局安装 CloudBase CLI ：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install -g @cloudbase/cli
|
|
||||||
```
|
|
||||||
|
|
||||||
2. 在项目根目录运行以下命令一键部署 VuePress 应用，在部署之前可以先 [开通环境](https://console.cloud.tencent.com/tcb/env/index?tdl_anchor=ad&tdl_site=vuejs)：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cloudbase init --without-template
|
|
||||||
cloudbase framework:deploy
|
|
||||||
```
|
|
||||||
|
|
||||||
CloudBase CLI 首先会跳转到控制台进行登录授权，然后将会交互式进行确认。
|
|
||||||
|
|
||||||
确认信息后会立即进行部署，部署完成后，可以获得一个自动 SSL，CDN 加速的网站应用，你也可以搭配使用 GitHub Action 来持续部署 GitHub 上的 VuePress 应用。
|
|
||||||
|
|
||||||
也可以使用 `cloudbase init --template vuepress` 快速创建和部署一个新的 VuePress 应用。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
更多详细信息请查看 CloudBase Framework 的[部署项目示例](https://github.com/TencentCloudBase/cloudbase-framework?site=vuepress#%E9%A1%B9%E7%9B%AE%E7%A4%BA%E4%BE%8B)
|
|
||||||
:::
|
|
||||||
|
|
||||||
## 21 云盒子
|
|
||||||
|
|
||||||
请查看 [21 云盒子 - 部署一个 VuePress 静态网页](https://www.21yunbox.com/docs/#/deploy-vuepress)。
|
|
||||||
1
docs/zh/guide/faq.md
Normal file
1
docs/zh/guide/faq.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# 常见问题
|
||||||
@ -1,70 +0,0 @@
|
|||||||
# 多语言支持
|
|
||||||
|
|
||||||
## 站点多语言配置
|
|
||||||
|
|
||||||
要启用 VuePress 的多语言支持，首先需要使用如下的文件目录结构：
|
|
||||||
|
|
||||||
```
|
|
||||||
docs
|
|
||||||
├─ README.md
|
|
||||||
├─ foo.md
|
|
||||||
├─ nested
|
|
||||||
│ └─ README.md
|
|
||||||
└─ zh
|
|
||||||
├─ README.md
|
|
||||||
├─ foo.md
|
|
||||||
└─ nested
|
|
||||||
└─ README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
然后，在你的 [配置文件](./configuration.md#配置文件) 中设置 `locales` 选项：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
locales: {
|
|
||||||
// 键名是该语言所属的子路径
|
|
||||||
// 作为特例，默认语言可以使用 '/' 作为其路径。
|
|
||||||
'/': {
|
|
||||||
lang: 'en-US',
|
|
||||||
title: 'VuePress',
|
|
||||||
description: 'Vue-powered Static Site Generator',
|
|
||||||
},
|
|
||||||
'/zh/': {
|
|
||||||
lang: 'zh-CN',
|
|
||||||
title: 'VuePress',
|
|
||||||
description: 'Vue 驱动的静态网站生成器',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
如果一个语言没有声明 `lang`, `title`, `description` 或者 `head` ，VuePress 将会尝试使用顶层配置的对应值。如果每个语言都声明了这些值，那么顶层配置中的对应值可以被省略。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
配置参考： [locales](../reference/config.md#locales)
|
|
||||||
:::
|
|
||||||
|
|
||||||
## 主题多语言配置
|
|
||||||
|
|
||||||
VuePress 没有限制主题如何提供多语言支持，因此每个主题可能会有不同的多语言配置方式，而且部分主题可能不会提供多语言支持。建议你查看主题本身的文档来获取更详细的指引。
|
|
||||||
|
|
||||||
如果你使用的是默认主题，那么它提供多语言支持的方式和上述是一致的：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
locales: {
|
|
||||||
'/': {
|
|
||||||
selectLanguageName: 'English',
|
|
||||||
},
|
|
||||||
'/zh/': {
|
|
||||||
selectLanguageName: '简体中文',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
配置参考： [默认主题 > locales](../reference/default-theme/config.md#locales)
|
|
||||||
:::
|
|
||||||
@ -1,369 +0,0 @@
|
|||||||
# Markdown
|
|
||||||
|
|
||||||
在阅读本章节之前，请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ，请先学习一些 [Markdown 教程](https://commonmark.org/help/)。
|
|
||||||
|
|
||||||
## 语法扩展
|
|
||||||
|
|
||||||
VuePress 会使用 [markdown-it](https://github.com/markdown-it/markdown-it) 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 [语法扩展](https://github.com/markdown-it/markdown-it#syntax-extensions) 。
|
|
||||||
|
|
||||||
本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。
|
|
||||||
|
|
||||||
你也可以通过 [markdown](../reference/config.md#markdown) 和 [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。
|
|
||||||
|
|
||||||
### 内置
|
|
||||||
|
|
||||||
由 markdown-it 内置支持：
|
|
||||||
|
|
||||||
- [表格](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
|
|
||||||
- [删除线](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
|
|
||||||
|
|
||||||
### 标题锚点
|
|
||||||
|
|
||||||
你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 `#` 锚点。点击这个 `#` 锚点，可以直接跳转到对应章节。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
标题锚点扩展由 [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) 支持。
|
|
||||||
|
|
||||||
配置参考： [markdown.anchor](../reference/config.md#markdown-anchor)
|
|
||||||
:::
|
|
||||||
|
|
||||||
### 链接
|
|
||||||
|
|
||||||
在你使用 Markdown 的 [链接语法](https://spec.commonmark.org/0.29/#link-reference-definitions) 时， VuePress 会为你进行一些转换。
|
|
||||||
|
|
||||||
以我们文档的源文件为例：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
└─ docs
|
|
||||||
└─ zh
|
|
||||||
├─ guide
|
|
||||||
│ ├─ getting-started.md
|
|
||||||
│ ├─ markdown.md # <- 我们在这里
|
|
||||||
│ └─ README.md
|
|
||||||
├─ reference
|
|
||||||
│ └─ config.md
|
|
||||||
└─ README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**原始 Markdown**
|
|
||||||
|
|
||||||
```md
|
|
||||||
[首页](/zh/README.md)
|
|
||||||
[指南](/zh/guide/)
|
|
||||||
[快速上手](./getting-started.md)
|
|
||||||
[markdown.links](../reference/config.md#links)
|
|
||||||
[GitHub](https://github.com)
|
|
||||||
```
|
|
||||||
|
|
||||||
**转换为**
|
|
||||||
|
|
||||||
```vue
|
|
||||||
<RouterLink to="/zh/">首页</RouterLink>
|
|
||||||
<RouterLink to="/zh/guide/">指南</RouterLink>
|
|
||||||
<RouterLink to="/zh/guide/getting-started.html">快速上手</RouterLink>
|
|
||||||
<RouterLink to="/zh/reference/config.html#links">markdown.links</RouterLink>
|
|
||||||
<a href="https://github.com" target="_blank" rel="noopener noreferrer">GitHub<OutboundLink/></a>
|
|
||||||
```
|
|
||||||
|
|
||||||
**渲染为**
|
|
||||||
|
|
||||||
[首页](/zh/README.md)
|
|
||||||
[指南](/zh/guide/)
|
|
||||||
[快速上手](./getting-started.md)
|
|
||||||
[markdown.links](../reference/config.md#links)
|
|
||||||
[GitHub](https://github.com)
|
|
||||||
|
|
||||||
**解释**
|
|
||||||
|
|
||||||
- 内部链接会被转换为 `<RouterLink>` 以便进行 SPA 导航。
|
|
||||||
- 指向 `.md` 文件的内部链接会被转换为目标页面的 [路由路径](./page.md#路由)，并且支持绝对路径和相对路径。
|
|
||||||
- 外部链接会被添加 `target="_blank" rel="noopener noreferrer"` 属性和一个 <OutboundLink /> 标记。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
链接扩展是由我们的内置插件支持的。
|
|
||||||
|
|
||||||
配置参考： [markdown.links](../reference/config.md#markdown-links)
|
|
||||||
|
|
||||||
参考: [內置组件 > OutboundLink](../reference/components.md#outboundlink)
|
|
||||||
:::
|
|
||||||
|
|
||||||
### Emoji :tada:
|
|
||||||
|
|
||||||
你可以在你的 Markdown 内容中输入 `:EMOJICODE:` 来添加 Emoji 表情。
|
|
||||||
|
|
||||||
前往 [emoji-cheat-sheet.com](https://emoji-cheat-sheet.com/) 来查看所有可用的 Emoji 表情和对应代码。
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```md
|
|
||||||
VuePress 2 已经发布 :tada: ！
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
VuePress 2 已经发布 :tada: ！
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
Emoji 扩展由 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) 支持。
|
|
||||||
|
|
||||||
配置参考： [markdown.emoji](../reference/config.md#markdown-emoji)
|
|
||||||
:::
|
|
||||||
|
|
||||||
### 目录
|
|
||||||
|
|
||||||
如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 `[[toc]]` 语法。
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```md
|
|
||||||
[[toc]]
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
[[toc]]
|
|
||||||
|
|
||||||
目录中的标题将会链接到对应的 [标题锚点](#标题锚点)，因此如果你禁用了标题锚点，可能会影响目录的功能。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
目录扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 [markdown-it-toc-done-right](https://github.com/nagaozen/markdown-it-toc-done-right)。
|
|
||||||
|
|
||||||
|
|
||||||
配置参考： [markdown.toc](../reference/config.md#markdown-toc)
|
|
||||||
:::
|
|
||||||
|
|
||||||
### 代码块
|
|
||||||
|
|
||||||
下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。
|
|
||||||
|
|
||||||
如果你想使用 [prism.js](https://prismjs.com/#basic-usage) 或 [highlight.js](https://highlightjs.org/) 在客户端进行语法高亮，你可以禁用我们的代码块扩展，然后手动在客户端引入你想要使用的库。
|
|
||||||
|
|
||||||
#### 语法高亮
|
|
||||||
|
|
||||||
VuePress 使用 [Prism](https://prismjs.com/) 来对代码块进行语法高亮。
|
|
||||||
|
|
||||||
Prism 支持多种编程语言，你可以前往 [Prism supported languages](https://prismjs.com/#supported-languages) 来查看所有可用的编程语言。
|
|
||||||
|
|
||||||
你只需要在代码块前添加对应语言的标识符，就可以启用代码高亮：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
```ts
|
|
||||||
import type { UserConfig } from '@vuepress/cli'
|
|
||||||
|
|
||||||
export const config: UserConfig = {
|
|
||||||
title: '你好， VuePress',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import type { UserConfig } from '@vuepress/cli'
|
|
||||||
|
|
||||||
export const config: UserConfig = {
|
|
||||||
title: '你好， VuePress',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
代码高亮扩展是由我们的内置插件支持的。
|
|
||||||
|
|
||||||
配置参考： [markdown.code.highlight](../reference/config.md#markdown-code-highlight)
|
|
||||||
:::
|
|
||||||
|
|
||||||
#### 行高亮
|
|
||||||
|
|
||||||
你可以在代码块添加行数范围标记，来为对应代码行进行高亮：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
```ts{1,6-8}
|
|
||||||
import type { UserConfig } from '@vuepress/cli'
|
|
||||||
|
|
||||||
export const config: UserConfig = {
|
|
||||||
title: '你好， VuePress',
|
|
||||||
|
|
||||||
themeConfig: {
|
|
||||||
logo: 'https://vuejs.org/images/logo.png',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
```ts{1,6-8}
|
|
||||||
import type { UserConfig } from '@vuepress/cli'
|
|
||||||
|
|
||||||
export const config: UserConfig = {
|
|
||||||
title: '你好， VuePress',
|
|
||||||
|
|
||||||
themeConfig: {
|
|
||||||
logo: 'https://vuejs.org/images/logo.png',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
行数范围标记的例子：
|
|
||||||
|
|
||||||
- 行数范围： `{5-8}`
|
|
||||||
- 多个单行： `{4,7,9}`
|
|
||||||
- 组合： `{4,7-13,16,23-27,40}`
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines)。
|
|
||||||
|
|
||||||
配置参考： [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines)
|
|
||||||
:::
|
|
||||||
|
|
||||||
#### 行号
|
|
||||||
|
|
||||||
你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。
|
|
||||||
|
|
||||||
你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置。
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
```ts
|
|
||||||
// 行号默认是启用的
|
|
||||||
const line2 = 'This is line 2'
|
|
||||||
const line3 = 'This is line 3'
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts:no-line-numbers
|
|
||||||
// 行号被禁用
|
|
||||||
const line2 = 'This is line 2'
|
|
||||||
const line3 = 'This is line 3'
|
|
||||||
```
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// 行号默认是启用的
|
|
||||||
const line2 = 'This is line 2'
|
|
||||||
const line3 = 'This is line 3'
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts:no-line-numbers
|
|
||||||
// 行号被禁用
|
|
||||||
const line2 = 'This is line 2'
|
|
||||||
const line3 = 'This is line 3'
|
|
||||||
```
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
行号扩展是由我们的内置插件支持的。
|
|
||||||
|
|
||||||
配置参考： [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers)
|
|
||||||
:::
|
|
||||||
|
|
||||||
#### 添加 v-pre
|
|
||||||
|
|
||||||
由于 [模板语法可以在 Markdown 中使用](#模板语法)，它也同样可以在代码块中生效。
|
|
||||||
|
|
||||||
为了避免你的代码块被 Vue 编译， VuePress 默认会在你的代码块添加 [v-pre](https://v3.vuejs.org/api/directives.html#v-pre) 指令。这一默认行为可以在配置中关闭。
|
|
||||||
|
|
||||||
|
|
||||||
你可以在代码块添加 `:v-pre` / `:no-v-pre` 标记来覆盖配置项中的设置。
|
|
||||||
|
|
||||||
::: warning
|
|
||||||
模板语法的字符有可能会被语法高亮器解析，比如 "Mustache" 语法（即双花括号）。因此，就像下面的例子一样，在某些语言中 `:no-v-pre` 可能并不能生效。
|
|
||||||
|
|
||||||
如果你无论如何都想在这种语言中使用 Vue 语法，你可以尝试禁用默认的语法高亮，然后在客户端实现你的自定义代码高亮。
|
|
||||||
:::
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
```md
|
|
||||||
<!-- 默认情况下，这里会被保持原样 -->
|
|
||||||
1 + 2 + 3 = {{ 1 + 2 + 3 }}
|
|
||||||
```
|
|
||||||
|
|
||||||
```md:no-v-pre
|
|
||||||
<!-- 这里会被 Vue 编译 -->
|
|
||||||
1 + 2 + 3 = {{ 1 + 2 + 3 }}
|
|
||||||
```
|
|
||||||
|
|
||||||
```js:no-v-pre
|
|
||||||
// 由于 JS 代码高亮，这里不会被正确编译
|
|
||||||
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
|
|
||||||
```
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
```md
|
|
||||||
<!-- 默认情况下，这里会被保持原样 -->
|
|
||||||
1 + 2 + 3 = {{ 1 + 2 + 3 }}
|
|
||||||
```
|
|
||||||
|
|
||||||
```md:no-v-pre
|
|
||||||
<!-- 这里会被 Vue 编译 -->
|
|
||||||
1 + 2 + 3 = {{ 1 + 2 + 3 }}
|
|
||||||
```
|
|
||||||
|
|
||||||
```js:no-v-pre
|
|
||||||
// 由于 JS 代码高亮，这里不会被正确编译
|
|
||||||
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
|
|
||||||
```
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
v-pre 扩展是由我们的内置插件支持的。
|
|
||||||
|
|
||||||
配置参考： [markdown.code.vPre](../reference/config.md#markdown-vpre)
|
|
||||||
:::
|
|
||||||
|
|
||||||
## 在 Markdown 中使用 Vue
|
|
||||||
|
|
||||||
这一章节会介绍 Vue 在 Markdown 中一些基本用法。
|
|
||||||
|
|
||||||
可以前往 [深入 > Markdown 和 Vue SFC](./advanced/markdown.md) 来了解更多内容。
|
|
||||||
|
|
||||||
### 模板语法
|
|
||||||
|
|
||||||
我们知道：
|
|
||||||
|
|
||||||
- Markdown 中允许使用 HTML。
|
|
||||||
- Vue 模板语法是和 HTML 兼容的。
|
|
||||||
|
|
||||||
这意味着， Markdown 中允许直接使用 [Vue 模板语法](https://v3.vuejs.org/guide/template-syntax.html)。
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```md
|
|
||||||
一加一等于： {{ 1 + 1 }}
|
|
||||||
|
|
||||||
<span v-for="i in 3"> span: {{ i }} </span>
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
一加一等于： {{ 1 + 1 }}
|
|
||||||
|
|
||||||
<span v-for="i in 3"> span: {{ i }} </span>
|
|
||||||
|
|
||||||
### 组件
|
|
||||||
|
|
||||||
你可以在 Markdown 中直接使用 Vue 组件。
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```md
|
|
||||||
这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
前往 [内置组件](../reference/components.md) 查看所有内置组件。
|
|
||||||
|
|
||||||
前往 [默认主题 > 内置组件](../reference/default-theme/components.md) 查看默认主题中的所有内置组件。
|
|
||||||
:::
|
|
||||||
@ -1,55 +0,0 @@
|
|||||||
# 页面
|
|
||||||
|
|
||||||
VuePress 是以 Markdown 为中心的。你项目中的每一个 Markdown 文件都是一个单独的页面。
|
|
||||||
|
|
||||||
## 路由
|
|
||||||
|
|
||||||
默认情况下，页面的路由路径是根据你的 Markdown 文件的相对路径决定的。
|
|
||||||
|
|
||||||
假设这是你的 Markdown 文件所处的目录结构：
|
|
||||||
|
|
||||||
```
|
|
||||||
└─ docs
|
|
||||||
├─ guide
|
|
||||||
│ ├─ getting-started.md
|
|
||||||
│ └─ README.md
|
|
||||||
├─ contributing.md
|
|
||||||
└─ README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
将 `docs` 目录作为你的 [sourceDir](../reference/cli.md) ，例如你在运行 `vuepress dev docs` 命令。此时，你的 Markdown 文件对应的路由路径为：
|
|
||||||
|
|
||||||
| 相对路径 | 路由路径 |
|
|
||||||
|--------------------|----------------------|
|
|
||||||
| `/README.md` | `/` |
|
|
||||||
| `/contributing.md` | `/contributing.html` |
|
|
||||||
| `/guide/README.md` | `/guide/` |
|
|
||||||
| `/guide/page.md` | `/guide/page.html` |
|
|
||||||
|
|
||||||
## Frontmatter
|
|
||||||
|
|
||||||
Markdown 文件可以包含一个 [YAML](https://yaml.org/) Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
lang: zh-CN
|
|
||||||
title: 页面的标题
|
|
||||||
description: 页面的描述
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
你肯定注意到 Frontmatter 中的字段和[配置文件](./configuration.md#config-file)中的[站点配置](./configuration.md#站点配置)十分类似。你可以通过 Frontmatter 来覆盖当前页面的 `lang`, `title`, `description` 等属性。因此，你可以把 Frontmatter 当作页面级作用域的配置。
|
|
||||||
|
|
||||||
同样的，VuePress 有一些内置支持的 Frontmatter 字段，而你使用的主题也可能有它自己的特殊 Frontmatter 。
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
前往 [Frontmatter 参考](../reference/config.md) 查看 VuePress 支持的 Frontmatter 配置。
|
|
||||||
|
|
||||||
前往 [默认主题 > Frontmatter 参考](../reference/default-theme/frontmatter.md) 查看默认主题的 Frontmatter 配置。
|
|
||||||
:::
|
|
||||||
|
|
||||||
## 内容
|
|
||||||
|
|
||||||
页面的主要内容是使用 Markdown 书写的。VuePress 首先会将 Markdown 转换为 HTML ，然后将 HTML 作为 Vue 单文件组件的 `<template>` 。
|
|
||||||
|
|
||||||
借助 [markdown-it](https://github.com/markdown-it/markdown-it) 和 Vue 模板语法的能力，基础的 Markdown 可以得到很多的扩展功能。接下来，前往 [Markdown](./markdown.md) 章节来了解 VuePress 中 Markdown 的扩展功能。
|
|
||||||
@ -1,45 +0,0 @@
|
|||||||
# 插件
|
|
||||||
|
|
||||||
借助于 [Plugin API](../references/plugin-api.md) ， VuePress 插件可以为你提供各种不同的功能。
|
|
||||||
|
|
||||||
## 社区插件
|
|
||||||
|
|
||||||
社区用户创建了很多插件，并将它们发布到了 [NPM](https://www.npmjs.com/search?q=keywords:vuepress-plugin) 上。 VuePress 团队也在 [@vuepress](https://www.npmjs.com/search?q=%40vuepress%20keywords%3Aplugin) Scope 下维护了一些官方插件。查看插件本身的文档可以获取更详细的指引。
|
|
||||||
|
|
||||||
一般而言，你需要在 [plugins](../reference/plugin-api.md#plugins) 配置项中设置你要使用的插件名称：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
plugins: [
|
|
||||||
'foo',
|
|
||||||
['bar', { /* 配置项 */ }]
|
|
||||||
],
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
你可以使用插件名称或者它的简称：
|
|
||||||
|
|
||||||
| 插件名称 | 简称 |
|
|
||||||
|---------------------------|---------------------|
|
|
||||||
| `vuepress-plugin-foo` | `foo` |
|
|
||||||
| `@org/vuepress-plugin-bar`| `@org/bar` |
|
|
||||||
| `@vuepress/plugin-foobar` | `@vuepress/foobar` |
|
|
||||||
|
|
||||||
## 本地插件
|
|
||||||
|
|
||||||
如果你想要使用自己的插件，但是又不想发布它，你可以创建一个本地插件。
|
|
||||||
|
|
||||||
推荐你直接将 [配置文件](./configuration.md#配置文件) 作为插件使用，因为 [几乎所有的插件 API 都可以在配置文件中使用](../reference/config.md#插件-api)，这在绝大多数场景下都更为方便。
|
|
||||||
|
|
||||||
但是如果你在配置文件中要做的事情太多了，最好还是将它们提取到单独的插件中，然后通过设置绝对路径或者通过 require 来使用它们：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
plugins: [
|
|
||||||
'/path/to/your-plugin.js',
|
|
||||||
require('./another-plugin'),
|
|
||||||
],
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
前往 [深入 > 开发插件](./advanced/plugin.md) 学习如何开发你自己的插件。
|
|
||||||
@ -1,52 +0,0 @@
|
|||||||
# 主题
|
|
||||||
|
|
||||||
VuePress 主题为你提供了布局、样式和其他功能，帮助你专注于 Markdown 内容的写作。
|
|
||||||
|
|
||||||
VuePress 有一个开箱即用的默认主题，正使用在你当前正在浏览的文档网站上。默认主题为文档网站提供了基础且实用的功能，你可以前往 [默认主题配置参考](../reference/default-theme/config.md) 获取全部的配置列表。
|
|
||||||
|
|
||||||
然而，你可能觉得默认主题不够出色。或者你想要搭建一个其他类型的网站而不是文档，比如博客。此时，你可以尝试 [使用社区主题](#社区主题) 或者 [创建本地主题](#本地主题)。
|
|
||||||
|
|
||||||
## 社区主题
|
|
||||||
|
|
||||||
社区用户创建了很多主题，并将它们发布到了 [NPM](https://www.npmjs.com/search?q=keywords:vuepress-theme) 上。查看主题本身的文档可以获取更详细的指引。
|
|
||||||
|
|
||||||
一般而言，你需要在 [theme](../reference/config.md#theme) 配置项中设置你要使用的主题名称：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
theme: 'foo',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
你可以使用主题名称或者它的简称：
|
|
||||||
|
|
||||||
| 主题名称 | 简称 |
|
|
||||||
|---------------------------|---------------------|
|
|
||||||
| `vuepress-theme-foo` | `foo` |
|
|
||||||
| `@org/vuepress-theme-bar` | `@org/bar` |
|
|
||||||
| `@vuepress/theme-default` | `@vuepress/default` |
|
|
||||||
|
|
||||||
## 本地主题
|
|
||||||
|
|
||||||
如果你想要使用自己的自定义主题，但是又不想发布它，你可以创建一个本地主题。
|
|
||||||
|
|
||||||
首先，创建本地主题目录，一般是 `.vuepress/theme` ：
|
|
||||||
|
|
||||||
```
|
|
||||||
└─ docs
|
|
||||||
├─ .vuepress
|
|
||||||
│ ├─ theme
|
|
||||||
│ │ └─ index.js
|
|
||||||
│ └─ config.js
|
|
||||||
└─ README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
然后，设置主题目录的绝对路径来使用它：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
theme: '/path/to/docs/.vuepress/theme',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
接下来，前往 [深入 > 开发主题](./advanced/theme.md) 学习如何开发你自己的主题。
|
|
||||||
1
docs/zh/reference/api.md
Normal file
1
docs/zh/reference/api.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# API
|
||||||
5
docs/zh/reference/api/README.md
Normal file
5
docs/zh/reference/api/README.md
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
---
|
||||||
|
sidebar: auto
|
||||||
|
---
|
||||||
|
|
||||||
|
# API
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# Vite
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# Webpack
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
10
docs/zh/reference/cli/README.md
Normal file
10
docs/zh/reference/cli/README.md
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
---
|
||||||
|
sidebar: auto
|
||||||
|
---
|
||||||
|
|
||||||
|
# 命令行工具
|
||||||
|
|
||||||
|
## create-fes-app
|
||||||
|
|
||||||
|
|
||||||
|
## fes
|
||||||
@ -1,56 +0,0 @@
|
|||||||
# 内置组件
|
|
||||||
|
|
||||||
## ClientOnly
|
|
||||||
|
|
||||||
- 使用：
|
|
||||||
|
|
||||||
```md
|
|
||||||
<ClientOnly>
|
|
||||||
<NonSsrFriendlyComponent />
|
|
||||||
</ClientOnly>
|
|
||||||
```
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该组件和它的子元素只会在客户端被渲染。也就是说，它不会在构建 (SSR) 过程中被渲染到 HTML 内。
|
|
||||||
|
|
||||||
如果一个组件在 `setup()` 中直接使用 浏览器 / DOM API ，它会导致构建过程报错，因为这些 API 在 Node.js 的环境中是无法使用的。在这种情况下，你可以选择一种方式：
|
|
||||||
|
|
||||||
- 修改这个组件，只在 `onBeforeMount()` 或 `onMounted()` Hook 中使用 浏览器 / DOM API 。
|
|
||||||
- 使用 `<ClientOnly>` 包裹这个组件。
|
|
||||||
|
|
||||||
## Content
|
|
||||||
|
|
||||||
- Props:
|
|
||||||
- pagePath
|
|
||||||
- 类型： `string`
|
|
||||||
- 是否必须： `false`
|
|
||||||
|
|
||||||
- 使用：
|
|
||||||
|
|
||||||
```md
|
|
||||||
<Content page-path="/" />
|
|
||||||
<Content page-path="/foo.html" />
|
|
||||||
```
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该组件会渲染页面的 Markdown 内容。
|
|
||||||
|
|
||||||
如果没有传入 `pagePath` Prop ，它会渲染当前路由路径下的页面。
|
|
||||||
|
|
||||||
该组件主要是为了开发主题时使用。在绝大多数情况下你不会用到它。
|
|
||||||
|
|
||||||
## OutboundLink
|
|
||||||
|
|
||||||
- 使用：
|
|
||||||
|
|
||||||
```md
|
|
||||||
<OutboundLink />
|
|
||||||
```
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该组件会渲染一个标识外部 URL 链接的图标。
|
|
||||||
|
|
||||||
该组件主要是为了开发主题时使用。在绝大多数情况下你不会用到它。
|
|
||||||
@ -1,3 +1,7 @@
|
|||||||
|
---
|
||||||
|
sidebar: auto
|
||||||
|
---
|
||||||
|
|
||||||
# 配置
|
# 配置
|
||||||
|
|
||||||
VuePress 配置的参考文档，可以通过配置文件来设置这些配置。 VuePress 约定的配置文件为（按照优先顺序）：
|
VuePress 配置的参考文档，可以通过配置文件来设置这些配置。 VuePress 约定的配置文件为（按照优先顺序）：
|
||||||
@ -1,106 +0,0 @@
|
|||||||
# 内置组件
|
|
||||||
|
|
||||||
## Badge <Badge text="badge" />
|
|
||||||
|
|
||||||
- Props:
|
|
||||||
- type
|
|
||||||
- 类型： `'tip' | 'warning' | 'danger'`
|
|
||||||
- 默认值： `'tip'`
|
|
||||||
- text
|
|
||||||
- 类型： `string`
|
|
||||||
- 默认值： `''`
|
|
||||||
- vertical
|
|
||||||
- 类型： `'top' | 'middle' | 'bottom' | undefined`
|
|
||||||
- 默认值： `undefined`
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```md
|
|
||||||
- VuePress - <Badge type="tip" text="v2" vertical="top" />
|
|
||||||
- VuePress - <Badge type="warning" text="v2" vertical="middle" />
|
|
||||||
- VuePress - <Badge type="danger" text="v2" vertical="bottom" />
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
- VuePress - <Badge type="tip" text="v2" vertical="top" />
|
|
||||||
- VuePress - <Badge type="warning" text="v2" vertical="middle" />
|
|
||||||
- VuePress - <Badge type="danger" text="v2" vertical="bottom" />
|
|
||||||
|
|
||||||
## CodeGroup
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
[CodeGroupItem](#codegroupitem) 组件的 Wrapper 。
|
|
||||||
|
|
||||||
## CodeGroupItem
|
|
||||||
|
|
||||||
- Props:
|
|
||||||
- title
|
|
||||||
- 类型： `string`
|
|
||||||
- 是否必需： `true`
|
|
||||||
- active
|
|
||||||
- 类型： `boolean`
|
|
||||||
- 默认值： `false`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该组件必须放置在 [CodeGroup](#codegroup) 组件的内部。
|
|
||||||
|
|
||||||
可以通过 `active` Prop 来设置初始激活的元素。如果不设置，默认激活第一个元素。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
<CodeGroup>
|
|
||||||
<CodeGroupItem title="YARN">
|
|
||||||
|
|
||||||
```bash:no-line-numbers
|
|
||||||
yarn
|
|
||||||
```
|
|
||||||
|
|
||||||
</CodeGroupItem>
|
|
||||||
|
|
||||||
<CodeGroupItem title="NPM" active>
|
|
||||||
|
|
||||||
```bash:no-line-numbers
|
|
||||||
npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
</CodeGroupItem>
|
|
||||||
</CodeGroup>
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
<CodeGroup>
|
|
||||||
<CodeGroupItem title="YARN">
|
|
||||||
|
|
||||||
```bash:no-line-numbers
|
|
||||||
yarn
|
|
||||||
```
|
|
||||||
|
|
||||||
</CodeGroupItem>
|
|
||||||
|
|
||||||
<CodeGroupItem title="NPM" active>
|
|
||||||
|
|
||||||
```bash:no-line-numbers
|
|
||||||
npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
</CodeGroupItem>
|
|
||||||
</CodeGroup>
|
|
||||||
|
|
||||||
::: warning
|
|
||||||
你必须在 `<CodeGroupItem>` 的开始标签和代码块之间添加一个空行，否则代码块无法被 Markdown 正确解析。
|
|
||||||
|
|
||||||
所有内容首先都必须是合法的 Markdown ，然后才是一个 Vue SFC 。
|
|
||||||
|
|
||||||
了解更多： [深入 > Markdown 与 Vue SFC](../../guide/advanced/markdown.md)
|
|
||||||
|
|
||||||
或者你可以选择使用 [自定义容器](./markdown.md#自定义容器) 。
|
|
||||||
:::
|
|
||||||
@ -1,603 +0,0 @@
|
|||||||
# 配置
|
|
||||||
|
|
||||||
默认主题配置的参考文档，可以通过 [themeConfig](../config.md#themeconfig) 来设置这些配置。
|
|
||||||
|
|
||||||
## 基础配置
|
|
||||||
|
|
||||||
### locales
|
|
||||||
|
|
||||||
- 类型： `{ [path: string]: Partial<DefaultThemeLocaleData> }`
|
|
||||||
|
|
||||||
- 默认值： `{}`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
多语言支持的各个语言 locales 。
|
|
||||||
|
|
||||||
所有在 [Locale 配置](#locale-配置) 章节内的配置项都可以在 locales 中使用。
|
|
||||||
|
|
||||||
该配置项仅能在默认主题内生效，注意不要和 [站点配置](../config.md#locales) 中的 `locales` 混淆。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [指南 > 多语言支持](../../guide/i18n.md)
|
|
||||||
|
|
||||||
## Locale 配置
|
|
||||||
|
|
||||||
该章节内的配置项可以作为一般配置使用，也可以使用在 [locales](#locales) 内。
|
|
||||||
|
|
||||||
### home
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `/`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
首页的路径。
|
|
||||||
|
|
||||||
它将被用于：
|
|
||||||
|
|
||||||
- 导航栏中 Logo 的链接
|
|
||||||
- 404 页面的 _返回首页_ 链接
|
|
||||||
|
|
||||||
### navbar
|
|
||||||
|
|
||||||
- 类型： `false | (NavbarItem | NavbarGroup | string)[]`
|
|
||||||
|
|
||||||
- 默认值： `[]`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
导航栏配置。
|
|
||||||
|
|
||||||
设置为 `false` 可以禁用导航栏。
|
|
||||||
|
|
||||||
为了配置导航栏元素，你可以将其设置为 _导航栏数组_ ，其中的每个元素是 `NavbarItem` 对象、 `NavbarGroup` 对象、或者字符串：
|
|
||||||
|
|
||||||
- `NavbarItem` 对象应该有一个 `text` 字段和一个 `link` 字段。
|
|
||||||
- `NavbarGroup` 对象应该有一个 `text` 字段和一个 `children` 字段。 `children` 字段同样是一个 _导航栏数组_ 。
|
|
||||||
- 字符串应为目标页面文件的路径。它将会被转换为 `NavbarItem` 对象，将页面标题作为 `text` ，将页面路由路径作为 `link` 。
|
|
||||||
|
|
||||||
- 示例 1：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
navbar: [
|
|
||||||
// NavbarItem
|
|
||||||
{
|
|
||||||
text: 'Foo',
|
|
||||||
link: '/foo/',
|
|
||||||
},
|
|
||||||
// NavbarGroup
|
|
||||||
{
|
|
||||||
text: 'Group',
|
|
||||||
children: ['/group/foo.md', '/group/bar.md'],
|
|
||||||
},
|
|
||||||
// 字符串 - 页面文件路径
|
|
||||||
'/bar/README.md',
|
|
||||||
],
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 示例 2：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
navbar: [
|
|
||||||
// 嵌套 Group - 最大深度为 2
|
|
||||||
{
|
|
||||||
text: 'Group',
|
|
||||||
children: [
|
|
||||||
{
|
|
||||||
text: 'SubGroup',
|
|
||||||
children: ['/group/sub/foo.md', '/group/sub/bar.md'],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### logo
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Logo 图片的 URL。
|
|
||||||
|
|
||||||
Logo 图片将会显示在导航栏的左端。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
// Public 文件路径
|
|
||||||
logo: '/hero.png',
|
|
||||||
// URL
|
|
||||||
logo: 'https://vuejs.org/images/logo.png',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [指南 > 静态资源 > Public 文件](../../guide/assets.md#public-文件)
|
|
||||||
|
|
||||||
### repo
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
项目仓库的 URL。
|
|
||||||
|
|
||||||
它将被用作 _仓库链接_ 的链接。_仓库链接_ 将会显示为导航栏的最后一个元素。
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
// 如果你按照 `organization/repository` 的格式设置它
|
|
||||||
// 我们会将它作为一个 GitHub 仓库
|
|
||||||
repo: 'vuejs/vuepress',
|
|
||||||
// 如果你使用的不是 GitHub ，可以直接使用 URL
|
|
||||||
repo: 'https://gitlab.com/foo/bar',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### repoLabel
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
项目仓库的标签。
|
|
||||||
|
|
||||||
它将被用作 _仓库链接_ 的文字。_仓库链接_ 将会显示为导航栏的最后一个元素。
|
|
||||||
|
|
||||||
如果你不明确指定该配置项，它将会根据 [repo](#repo) 配置项自动推断。
|
|
||||||
|
|
||||||
### selectLanguageText
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
_选择语言菜单_ 的文字。
|
|
||||||
|
|
||||||
如果你在站点配置中设置了多个 [locales](../config.md#locales) ，那么 _选择语言菜单_ 就会显示在导航栏中仓库按钮的旁边。
|
|
||||||
|
|
||||||
### selectLanguageAriaLabel
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
_选择语言菜单_ 的 `aria-label` 属性。
|
|
||||||
|
|
||||||
它主要是为了站点的可访问性 (a11y) 。
|
|
||||||
|
|
||||||
### selectLanguageName
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Locale 的语言名称。
|
|
||||||
|
|
||||||
该配置项 **仅能在主题配置的 [locales](#locales) 的内部生效** 。它将被用作 locale 的语言名称，展示在 _选择语言菜单_ 内。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
locales: {
|
|
||||||
'/': {
|
|
||||||
lang: 'en-US',
|
|
||||||
},
|
|
||||||
'/zh/': {
|
|
||||||
lang: 'zh-CN',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
themeConfig: {
|
|
||||||
locales: {
|
|
||||||
'/': {
|
|
||||||
selectLanguageName: 'English',
|
|
||||||
},
|
|
||||||
'/zh/': {
|
|
||||||
selectLanguageName: '简体中文',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### sidebar
|
|
||||||
|
|
||||||
- 类型： `false | 'auto' | SidebarConfigArray | SidebarConfigObject`
|
|
||||||
|
|
||||||
- 默认值： `'auto'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
侧边栏配置。
|
|
||||||
|
|
||||||
你可以通过页面的 [sidebar](./frontmatter.md#sidebar) frontmatter 来覆盖这个全局配置。
|
|
||||||
|
|
||||||
设置为 `false` 可以禁用侧边栏。
|
|
||||||
|
|
||||||
如果你设置为 `'auto'`，侧边栏会根据页面标题自动生成。
|
|
||||||
|
|
||||||
为了手动配置侧边栏元素，你可以将其设置为 _侧边栏数组_ ，其中的每个元素是 `SidebarItem` 对象、 `SidebarGroup` 对象、或者字符串：
|
|
||||||
|
|
||||||
- `SidebarItem` 对象应该有一个 `text` 字段、一个 `link` 字段和一个 `children` 字段。 `children` 字段是一个由 `SidebarItem` 或者字符串组成的数组。
|
|
||||||
- `SidebarGroup` 对象应将 `isGroup` 字段设为 `true` ，并且应该有一个 `text` 字段和一个`children` 字段。 `children` 字段是一个由 `SidebarItem` 或者字符串组成的数组。
|
|
||||||
- 字符串应为目标页面文件的路径。它将会被转换为 `SidebarItem` 对象，将页面标题作为 `text` ，将页面路由路径作为 `link` ，并根据页面标题自动生成 `children` 。
|
|
||||||
|
|
||||||
如果你想在不同子路径中使用不同的侧边栏，你可以将该配置项设置为 _侧边栏对象_ ：
|
|
||||||
|
|
||||||
- Key 为路径前缀。
|
|
||||||
- Value 为 _侧边栏数组_ 。
|
|
||||||
|
|
||||||
- 示例 1：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
// 侧边栏数组
|
|
||||||
// 所有页面会使用相同的侧边栏
|
|
||||||
sidebar: [
|
|
||||||
// SidebarItem
|
|
||||||
{
|
|
||||||
text: 'Foo',
|
|
||||||
link: '/foo/',
|
|
||||||
children: [
|
|
||||||
// SidebarItem
|
|
||||||
{
|
|
||||||
text: 'github',
|
|
||||||
link: 'https://github.com',
|
|
||||||
children: [],
|
|
||||||
},
|
|
||||||
// 字符串 - 页面文件路径
|
|
||||||
'/foo/bar.md',
|
|
||||||
],
|
|
||||||
},
|
|
||||||
// SidebarGroup
|
|
||||||
{
|
|
||||||
isGroup: true,
|
|
||||||
text: 'Group',
|
|
||||||
children: ['/group/foo.md', '/group/bar.md'],
|
|
||||||
},
|
|
||||||
// 字符串 - 页面文件路径
|
|
||||||
'/bar/README.md',
|
|
||||||
],
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 示例 2：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
// 侧边栏对象
|
|
||||||
// 不同子路径下的页面会使用不同的侧边栏
|
|
||||||
sidebar: {
|
|
||||||
'/guide/': [
|
|
||||||
{
|
|
||||||
isGroup: true,
|
|
||||||
text: 'Guide',
|
|
||||||
children: ['/guide/README.md', '/guide/getting-started.md'],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
'/reference/': [
|
|
||||||
{
|
|
||||||
isGroup: true,
|
|
||||||
text: 'Reference',
|
|
||||||
children: ['/reference/cli.md', '/reference/config.md'],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### editLink
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 _编辑此页_ 链接。
|
|
||||||
|
|
||||||
你可以通过页面的 [editLink](./frontmatter.md#editlink) frontmatter 来覆盖这个全局配置。
|
|
||||||
|
|
||||||
### editLinkText
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'Edit this page'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
_编辑此页_ 链接的文字。
|
|
||||||
|
|
||||||
### editLinkPattern
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
_编辑此页_ 链接的 Pattern 。
|
|
||||||
|
|
||||||
它将会用于生成 _编辑此页_ 的链接。
|
|
||||||
|
|
||||||
如果你不设置该选项，则会根据 [docsRepo](#docsrepo) 配置项来推断 Pattern 。但是如果你的文档仓库没有托管在常用的平台上，比如 GitHub 、 GitLab 、 Bitbucket 等，那么你必须设置该选项才能使 _编辑此页_ 链接正常工作。
|
|
||||||
|
|
||||||
- 用法：
|
|
||||||
|
|
||||||
| Pattern | 描述 |
|
|
||||||
|-----------|----------------------------------------------------------------|
|
|
||||||
| `:repo` | 文档仓库 URL ，即 [docsRepo](#docsrepo) |
|
|
||||||
| `:branch` | 文档仓库分支 ，即 [docsBranch](#docsbranch) |
|
|
||||||
| `:path` | 页面源文件的路径，即 [docsDir](#docsdir) 拼接上页面文件的相对路径 |
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
themeConfig: {
|
|
||||||
docsRepo: 'https://gitlab.com/owner/name',
|
|
||||||
docsBranch: 'master',
|
|
||||||
docsDir: 'docs',
|
|
||||||
editLinkPattern: ':repo/-/edit/:branch/:path',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
则会生成类似于 `'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md'` 的链接。
|
|
||||||
|
|
||||||
### docsRepo
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
文档源文件的仓库 URL 。
|
|
||||||
|
|
||||||
它将会用于生成 _编辑此页_ 的链接。
|
|
||||||
|
|
||||||
如果你不设置该选项，则默认会使用 [repo](#repo) 配置项。但是如果你的文档源文件是在一个不同的仓库内，你就需要设置该配置项了。
|
|
||||||
|
|
||||||
### docsBranch
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'main'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
文档源文件的仓库分支。
|
|
||||||
|
|
||||||
它将会用于生成 _编辑此页_ 的链接。
|
|
||||||
|
|
||||||
### docsDir
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `''`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
文档源文件存放在仓库中的目录名。
|
|
||||||
|
|
||||||
它将会用于生成 _编辑此页_ 的链接。
|
|
||||||
|
|
||||||
### lastUpdated
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 _最近更新时间戳_ 。
|
|
||||||
|
|
||||||
你可以通过页面的 [lastUpdated](./frontmatter.md#lastupdated) frontmatter 来覆盖这个全局配置。
|
|
||||||
|
|
||||||
要注意的是，如果你将 `themeConfig.lastUpdated` 设为了 `false` ，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。
|
|
||||||
|
|
||||||
### lastUpdatedText
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'Last Updated'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
_最近更新时间戳_ 标签的文字。
|
|
||||||
|
|
||||||
### contributors
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 _贡献者列表_ 。
|
|
||||||
|
|
||||||
你可以通过页面的 [contributors](./frontmatter.md#contributors) frontmatter 来覆盖这个全局配置。
|
|
||||||
|
|
||||||
要注意的是，如果你将 `themeConfig.contributors` 设为了 `false` ，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。
|
|
||||||
|
|
||||||
### contributorsText
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'Contributors'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
_贡献者列表_ 标签的文字。
|
|
||||||
|
|
||||||
### tip
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'TIP'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Tip [自定义容器](./markdown.md#自定义容器) 的默认标题。
|
|
||||||
|
|
||||||
### warning
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'WARNING'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Warning [自定义容器](./markdown.md#自定义容器) 的默认标题。
|
|
||||||
|
|
||||||
### danger
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'WARNING'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Danger [自定义容器](./markdown.md#自定义容器) 的默认标题。
|
|
||||||
|
|
||||||
### notFound
|
|
||||||
|
|
||||||
- 类型： `string[]`
|
|
||||||
|
|
||||||
- 默认值： `['Not Found']`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
404 页面的提示信息。
|
|
||||||
|
|
||||||
当用户进入 404 页面时，会从数组中随机选取一条信息进行展示。
|
|
||||||
|
|
||||||
### backToHome
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'Back to home'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
404 页面中 _返回首页_ 链接的文字。
|
|
||||||
|
|
||||||
### openInNewWindow
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 默认值： `'open in new window'`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
[OutboundLink](../components.md#outboundlink) 链接内的 `sr-only` 文字。
|
|
||||||
|
|
||||||
它主要是为了站点的可访问性 (a11y) 。
|
|
||||||
|
|
||||||
## 插件
|
|
||||||
|
|
||||||
### themePlugins
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
设置默认主题使用的插件。
|
|
||||||
|
|
||||||
默认主题使用了一些插件，如果你确实不需要该插件，你可以选择禁用它。在禁用插件之前，请确保你已了解它的用途。
|
|
||||||
|
|
||||||
#### themePlugins.activeHeaderLinks
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 [@vuepress/plugin-active-header-links](../plugin/active-header-links.md) 。
|
|
||||||
|
|
||||||
#### themePlugins.backToTop
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 [@vuepress/plugin-back-to-top](../plugin/back-to-top.md) 。
|
|
||||||
|
|
||||||
#### themePlugins.container
|
|
||||||
|
|
||||||
- 类型： `Record<ContainerType, boolean>`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用由 [@vuepress/plugin-container](../plugin/container.md) 支持的自定义容器。
|
|
||||||
|
|
||||||
`ContainerType` 类型为：
|
|
||||||
|
|
||||||
- `tip`
|
|
||||||
- `warning`
|
|
||||||
- `danger`
|
|
||||||
- `details`
|
|
||||||
- `codeGroup`
|
|
||||||
- `codeGroupItem`
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [默认主题 > Markdown > 自定义容器](./markdown.md#自定义容器)
|
|
||||||
|
|
||||||
#### themePlugins.debug
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 [@vuepress/plugin-debug](../plugin/debug.md) 。
|
|
||||||
|
|
||||||
#### themePlugins.git
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 [@vuepress/plugin-git](../plugin/git.md) 。
|
|
||||||
|
|
||||||
#### themePlugins.mediumZoom
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 [@vuepress/plugin-medium-zoom](../plugin/medium-zoom.md) 。
|
|
||||||
|
|
||||||
#### themePlugins.nprogress
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `true`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否启用 [@vuepress/plugin-nprogress](../plugin/nprogress.md) 。
|
|
||||||
@ -1,253 +0,0 @@
|
|||||||
# Frontmatter
|
|
||||||
|
|
||||||
## 首页
|
|
||||||
|
|
||||||
本章节中的 Frontmatter 只会在首页中生效。
|
|
||||||
|
|
||||||
### home
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
设定该页面是首页还是普通页面。
|
|
||||||
|
|
||||||
如果你不设置该 Frontmatter 或将其设为 `false` ，则该页面会是一个 [普通页面](#普通页面)
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
home: true
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### heroImage
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
首页图片的 URL 。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
# Public 文件路径
|
|
||||||
heroImage: /hero.png
|
|
||||||
# URL
|
|
||||||
heroImage: https://vuejs.org/images/logo.png
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [指南 > 静态资源 > Public 文件](../../guide/assets.md#public-文件)
|
|
||||||
|
|
||||||
### heroAlt
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
首页图片的 `alt` 属性。
|
|
||||||
|
|
||||||
如果不设置，则默认使用 [heroText](#heroText) 。
|
|
||||||
|
|
||||||
### heroText
|
|
||||||
|
|
||||||
- 类型： `string | null`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
首页的大标题。
|
|
||||||
|
|
||||||
如果不设置，则默认使用站点 [title](../config.md#title) 。
|
|
||||||
|
|
||||||
设置为 `null` 来禁用首页大标题。
|
|
||||||
|
|
||||||
### tagline
|
|
||||||
|
|
||||||
- 类型： `string | null`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
首页的标语。
|
|
||||||
|
|
||||||
如果不设置，则默认使用站点 [description](../config.md#description) 。
|
|
||||||
|
|
||||||
设置为 `null` 来禁用首页标语。
|
|
||||||
|
|
||||||
### actions
|
|
||||||
|
|
||||||
- 类型：
|
|
||||||
|
|
||||||
```ts
|
|
||||||
Array<{
|
|
||||||
text: string
|
|
||||||
link: string
|
|
||||||
type?: 'primary' | 'secondary'
|
|
||||||
}>
|
|
||||||
```
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
配置首页按钮。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
actions:
|
|
||||||
- text: 快速上手
|
|
||||||
link: /zh/guide/getting-started.html
|
|
||||||
type: primary
|
|
||||||
- text: 项目简介
|
|
||||||
link: /guide/
|
|
||||||
type: secondary
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### features
|
|
||||||
|
|
||||||
- 类型：
|
|
||||||
|
|
||||||
```ts
|
|
||||||
Array<{
|
|
||||||
title: string
|
|
||||||
details: string
|
|
||||||
}>
|
|
||||||
```
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
配置首页特性列表。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
features:
|
|
||||||
- title: 简洁至上
|
|
||||||
details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
|
|
||||||
- title: Vue 驱动
|
|
||||||
details: 享受 Vue 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。
|
|
||||||
- title: 高性能
|
|
||||||
details: VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### footer
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
首页的页脚。
|
|
||||||
|
|
||||||
### footerHtml
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否允许页脚中使用 HTML 。
|
|
||||||
|
|
||||||
如果设置为 `true` ，那么 [footer](#footer) 会被作为 HTML 代码处理。
|
|
||||||
|
|
||||||
## 普通页面
|
|
||||||
|
|
||||||
本章节中的 Frontmatter 只会在普通页面中生效。
|
|
||||||
|
|
||||||
### editLink
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否在本页面中启用 _编辑此页_ 链接。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [默认主题 > 配置 > editLink](./config.md#editlink)
|
|
||||||
|
|
||||||
### lastUpdated
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否在本页面中启用 _最近更新时间戳_ 。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [默认主题 > 配置 > lastUpdated](./config.md#lastupdated)
|
|
||||||
|
|
||||||
### contributors
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
是否在本页面中启用 _贡献者列表_ 。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [默认主题 > 配置 > contributors](./config.md#contributors)
|
|
||||||
|
|
||||||
### sidebar
|
|
||||||
|
|
||||||
- 类型： `false | 'auto' | SidebarConfigArray | SidebarConfigObject`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
配置本页面的侧边栏。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [默认主题 > 配置 > sidebar](./config.md#sidebar)
|
|
||||||
|
|
||||||
### prev
|
|
||||||
|
|
||||||
- 类型： `NavLink | string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
上一个页面的链接。
|
|
||||||
|
|
||||||
如果你不设置该 Frontmatter ，该链接会自动根据侧边栏配置进行推断。
|
|
||||||
|
|
||||||
为了手动配置上一页面的链接，你可以将其设置为一个 `NavLink` 对象或者一个字符串：
|
|
||||||
|
|
||||||
- `NavLink` 对象应该有一个 `text` 字段和一个 `link` 字段。
|
|
||||||
- 字符串应为目标页面文件的路径。它将会被转换为 `NavLink` 对象，将页面标题作为 `text` ，将页面路由路径作为 `link` 。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
# NavLink
|
|
||||||
prev:
|
|
||||||
text: Get Started
|
|
||||||
link: /guide/getting-started.html
|
|
||||||
|
|
||||||
# NavLink - 外部 URL
|
|
||||||
prev:
|
|
||||||
text: GitHub
|
|
||||||
link: https://github.com
|
|
||||||
|
|
||||||
# 字符串 - 页面文件路径
|
|
||||||
prev: /guide/getting-started.md
|
|
||||||
|
|
||||||
# 字符串 - 页面文件相对路径
|
|
||||||
prev: ../../guide/getting-started.md
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### next
|
|
||||||
|
|
||||||
- 类型： `NavLink | string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
下一个页面的链接。
|
|
||||||
|
|
||||||
如果你不设置该 Frontmatter ，该链接会自动根据侧边栏配置进行推断。
|
|
||||||
|
|
||||||
类型和 [prev](#prev) Frontmatter 相同。
|
|
||||||
@ -1,124 +0,0 @@
|
|||||||
# Markdown
|
|
||||||
|
|
||||||
## 自定义容器
|
|
||||||
|
|
||||||
- 使用：
|
|
||||||
|
|
||||||
```md
|
|
||||||
::: <type> [title]
|
|
||||||
[content]
|
|
||||||
:::
|
|
||||||
```
|
|
||||||
|
|
||||||
`type` 是必需的， `title` 和 `content` 是可选的。
|
|
||||||
|
|
||||||
支持的 `type` 有：
|
|
||||||
- `tip`
|
|
||||||
- `warning`
|
|
||||||
- `danger`
|
|
||||||
- `details`
|
|
||||||
- [CodeGroup](./components.md#codegroup) 和 [CodeGroupItem](./components.md#codegroupitem) 的别名：
|
|
||||||
- `code-group`
|
|
||||||
- `code-group-item`
|
|
||||||
|
|
||||||
- 示例 1 （默认标题）：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
```md
|
|
||||||
::: tip
|
|
||||||
这是一个提示
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: warning
|
|
||||||
这是一个警告
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: danger
|
|
||||||
这是一个危险警告
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: details
|
|
||||||
这是一个 details 标签，在 IE / Edge 中不生效
|
|
||||||
:::
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
::: tip
|
|
||||||
这是一个提示
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: warning
|
|
||||||
这是一个警告
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: danger
|
|
||||||
这是一个危险警告
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: details
|
|
||||||
这是一个 details 标签，在 IE / Edge 中不生效
|
|
||||||
:::
|
|
||||||
|
|
||||||
- 示例 2 （自定义标题）：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
::: danger STOP
|
|
||||||
危险区域，禁止通行
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: details 点击查看代码
|
|
||||||
```js
|
|
||||||
console.log('你好，VuePress！')
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
::: danger STOP
|
|
||||||
危险区域，禁止通行
|
|
||||||
:::
|
|
||||||
|
|
||||||
::: details 点击查看代码
|
|
||||||
```js
|
|
||||||
console.log('你好，VuePress！')
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
|
|
||||||
- 示例 3 （Code Group 别名）：
|
|
||||||
|
|
||||||
**输入**
|
|
||||||
|
|
||||||
````md
|
|
||||||
:::: code-group
|
|
||||||
::: code-group-item FOO
|
|
||||||
```js
|
|
||||||
const foo = 'foo'
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
::: code-group-item BAR
|
|
||||||
```js
|
|
||||||
const bar = 'bar'
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
::::
|
|
||||||
````
|
|
||||||
|
|
||||||
**输出**
|
|
||||||
|
|
||||||
:::: code-group
|
|
||||||
::: code-group-item FOO
|
|
||||||
```js
|
|
||||||
const foo = 'foo'
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
::: code-group-item BAR
|
|
||||||
```js
|
|
||||||
const bar = 'bar'
|
|
||||||
```
|
|
||||||
:::
|
|
||||||
::::
|
|
||||||
@ -1,165 +0,0 @@
|
|||||||
# Frontmatter
|
|
||||||
|
|
||||||
## lang
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面的语言。
|
|
||||||
|
|
||||||
它将会覆盖站点配置中的 `lang` 配置项
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [配置 > lang](./config.md#lang)
|
|
||||||
|
|
||||||
## title
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面的标题。
|
|
||||||
|
|
||||||
如果你不在 Frontmatter 中设置 `title` ，那么页面中第一个一级标题（即 `# title`）的内容会被当作标题使用。
|
|
||||||
|
|
||||||
## description
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面的描述。
|
|
||||||
|
|
||||||
它将会覆盖站点配置中的 `description` 配置项
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [配置 > description](./config.md#description)
|
|
||||||
|
|
||||||
## head
|
|
||||||
|
|
||||||
- 类型： `HeadConfig[]`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面 `<head>` 标签内添加的额外标签。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
head:
|
|
||||||
- - meta
|
|
||||||
- name: foo
|
|
||||||
content: bar
|
|
||||||
- - link
|
|
||||||
- rel: canonical
|
|
||||||
href: foobar
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
渲染为：
|
|
||||||
|
|
||||||
```html
|
|
||||||
<head>
|
|
||||||
<meta name="foo" content="bar" />
|
|
||||||
<link rel="canonical" href="foobar" />
|
|
||||||
</head>
|
|
||||||
```
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [配置 > head](./config.md#head)
|
|
||||||
|
|
||||||
## date
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面的创建日期。
|
|
||||||
|
|
||||||
应按照 `yyyy-MM-dd` 的格式来指定日期，或者遵循 [YAML Timestamp Type](https://yaml.org/type/timestamp.html) 。
|
|
||||||
|
|
||||||
## permalink
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面的永久链接。
|
|
||||||
|
|
||||||
它将会覆盖根据文件路径来决定的默认路由路径。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [Frontmatter > permalinkPattern](#permalinkpattern)
|
|
||||||
- [指南 > 页面 > 路由](../guide/page.md#路由)
|
|
||||||
|
|
||||||
## permalinkPattern
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
为页面生成永久链接的 Pattern 。
|
|
||||||
|
|
||||||
如果 Frontmatter 中设置了 `permalink` ，那么这个字段则不会生效。
|
|
||||||
|
|
||||||
- 使用：
|
|
||||||
|
|
||||||
| Pattern | 描述 |
|
|
||||||
|-----------|-------------------|
|
|
||||||
| `:year` | 创建日期的 年 部分 |
|
|
||||||
| `:month` | 创建日期的 月 部分 |
|
|
||||||
| `:day` | 创建日期的 日 部分 |
|
|
||||||
| `:slug` | 页面文件名的 Slug |
|
|
||||||
| `:raw` | 原始路由路径 |
|
|
||||||
|
|
||||||
`:year`, `:month` 和 `:day` Pattern 根据如下优先级进行解析：
|
|
||||||
|
|
||||||
- Frontmatter 中的 `date` 字段。
|
|
||||||
- 符合 `yyyy-MM-dd-foobar.md` 或 `yyyy-MM-foobar.md` 日期格式的文件名。
|
|
||||||
- 符合 `yyyy/MM/dd/foobar.md` 或 `yyyy/MM/foobar.md` 日期格式的目录名。
|
|
||||||
- 默认值 `1970-01-01` 。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
- 情况 1：
|
|
||||||
|
|
||||||
页面文件名是 `foo-bar.md` 。
|
|
||||||
|
|
||||||
页面 Frontmatter 是：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
date: 2021-01-03
|
|
||||||
permalinkPattern: :year/:month/:day/:slug.html
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
那么页面的永久链接将会是 `2021/01/03/foo-bar.html` 。
|
|
||||||
|
|
||||||
- 情况 2：
|
|
||||||
|
|
||||||
页面文件名是 `2021-01-03-bar-baz.md`。
|
|
||||||
|
|
||||||
页面 Frontmatter 是：
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
permalinkPattern: :year/:month/:day/:slug.html
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
那么页面的永久链接将会是 `2021/01/03/bar-baz.html` 。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [Frontmatter > date](#date)
|
|
||||||
- [Frontmatter > permalink](#permalink)
|
|
||||||
|
|
||||||
## layout
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面的布局。
|
|
||||||
@ -1,285 +0,0 @@
|
|||||||
# 插件 API
|
|
||||||
|
|
||||||
插件需要在初始化之前使用。基础配置项会在使用插件时立即被处理：
|
|
||||||
|
|
||||||
- [name](#name)
|
|
||||||
- [multiple](#multiple)
|
|
||||||
- [plugins](#plugins)
|
|
||||||
|
|
||||||
下列 Hooks 会在初始化 App 时处理：
|
|
||||||
|
|
||||||
- [extendsMarkdown](#extendsmarkdown)
|
|
||||||
- [onInitialized](#oninitialized)
|
|
||||||
|
|
||||||
下列 Hooks 会在准备文件时处理：
|
|
||||||
|
|
||||||
- [extendsPageData](#extendspagedata)
|
|
||||||
- [clientAppEnhanceFiles](#clientappenhancefiles)
|
|
||||||
- [clientAppRootComponentFiles](#clientapprootcomponentfiles)
|
|
||||||
- [clientAppSetupFiles](#clientappsetupfiles)
|
|
||||||
- [onPrepared](#onprepared)
|
|
||||||
|
|
||||||
下列 Hooks 会在 dev / build 时处理：
|
|
||||||
|
|
||||||
- [alias](#alias)
|
|
||||||
- [define](#define)
|
|
||||||
- [onGenerated](#ongenerated)
|
|
||||||
|
|
||||||
## 基础配置项
|
|
||||||
|
|
||||||
### name
|
|
||||||
|
|
||||||
- 类型： `string`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
插件的名称。
|
|
||||||
|
|
||||||
它会被用来识别插件，以避免多次使用同一个插件，因此应确保你的插件名称是独一无二的。
|
|
||||||
|
|
||||||
建议使用以下命名格式：
|
|
||||||
|
|
||||||
- 非 Scoped: `vuepress-plugin-foo`
|
|
||||||
- Scoped: `@org/vuepress-plugin-foo`
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [插件 API > multiple](#multiple)
|
|
||||||
|
|
||||||
### multiple
|
|
||||||
|
|
||||||
- 类型： `boolean`
|
|
||||||
|
|
||||||
- 默认值： `false`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
插件是否能够被多次使用。
|
|
||||||
|
|
||||||
如果设置为 `false` ，当有相同名称的插件被使用时，先使用的会被后使用的替换掉。
|
|
||||||
|
|
||||||
如果设置为 `true` ，相同名称的插件可以被多次使用且不会被替换。
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [插件 API > name](#name)
|
|
||||||
|
|
||||||
### plugins
|
|
||||||
|
|
||||||
- 类型： `PluginConfig[]`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
要使用的插件。
|
|
||||||
|
|
||||||
一个插件可以通过该选项来使用其他的插件。
|
|
||||||
|
|
||||||
该配置项接收一个数组，其中的每一个数组项是一个包含两个元素的元组：
|
|
||||||
|
|
||||||
- 第一个元素是插件名称或插件本身。它可以接收插件名称、插件简称、插件的绝对路径或插件对象。
|
|
||||||
- 第二个元素是插件选项。它可以接收布尔值或一个对象。设置为 `false` 可以禁用该插件。设置为 `true` 可以启用该插件但不设置任何选项。使用对象可以启用该插件并且传入选项。
|
|
||||||
|
|
||||||
为了简便起见，你可以将上述元组的第一个元素直接作为数组项，它等价于启用该插件但不设置任何选项。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
plugins: [
|
|
||||||
// 包含两个元素的元组
|
|
||||||
['vuepress-plugin-foo', false],
|
|
||||||
['bar', true],
|
|
||||||
['/path/to/local/plugin', { /* 选项 */ }],
|
|
||||||
[require('vuepress-plugin-baz'), true],
|
|
||||||
|
|
||||||
// 只使用第一个元素
|
|
||||||
'foobar', // 等价于 ['foobar', true]
|
|
||||||
],
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 参考：
|
|
||||||
- [指南 > 插件](../guide/plugin.md)
|
|
||||||
|
|
||||||
## 开发 Hooks
|
|
||||||
|
|
||||||
### alias
|
|
||||||
|
|
||||||
- 类型： `Record<string, any> | ((app: App) => Record<string, any>)`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
定义路径别名。
|
|
||||||
|
|
||||||
该 Hook 接收一个对象，或者一个返回对象的函数。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
alias: {
|
|
||||||
'@alias': '/path/to/alias',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### define
|
|
||||||
|
|
||||||
- 类型： `Record<string, any> | ((app: App) => Record<string, any>)`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
定义全局常量。
|
|
||||||
|
|
||||||
该 Hook 接收一个对象，或者一个返回对象的函数。
|
|
||||||
|
|
||||||
它可以被用于向客户端文件传递变量。注意这里的值都会自动被 `JSON.stringify()` 处理。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
define: {
|
|
||||||
__GLOBAL_BOOLEAN__: true,
|
|
||||||
__GLOBAL_STRING__: 'foobar',
|
|
||||||
__GLOBAL_OBJECT__: { foo: 'bar' },
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### extendsMarkdown
|
|
||||||
|
|
||||||
- 类型： `(md: Markdown, app: App) => void`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Markdown 增强。
|
|
||||||
|
|
||||||
该 Hook 接收一个函数，在参数中会收到一个由 [markdown-it](https://github.com/markdown-it/markdown-it) 提供的 `Markdown` 实例。
|
|
||||||
|
|
||||||
它可以用来添加额外的 markdown-it 插件、应用额外的自定义功能。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
extendsMarkdown: (md) => {
|
|
||||||
md.use(plugin1)
|
|
||||||
md.linkify.set({ fuzzyEmail: false })
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### extendsPageData
|
|
||||||
|
|
||||||
- 类型： `(page: Page, app: App) => Record<string, any> | Promise<Record<string, any>>`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
页面数据扩展。
|
|
||||||
|
|
||||||
该 Hook 接收一个函数，在参数中会收到一个 `Page` 实例。返回的对象会被合并到页面数据中，可以在客户端代码中使用。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
extendsPageData: (page) => {
|
|
||||||
const meta = 'foobar'
|
|
||||||
return { meta }
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
在客户端组件中：
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { usePageData } from '@vuepress/client'
|
|
||||||
|
|
||||||
export default {
|
|
||||||
setup() {
|
|
||||||
const page = usePageData()
|
|
||||||
console.log(page.value.meta) // foobar
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 客户端文件 Hooks
|
|
||||||
|
|
||||||
### clientAppEnhanceFiles
|
|
||||||
|
|
||||||
- 类型： `string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Client App Enhancement 文件路径。
|
|
||||||
|
|
||||||
该 Hook 接收文件绝对路径，或者一个返回路径的函数。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
clientAppEnhanceFiles: '/path/to/clientAppEnhance.js',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### clientAppRootComponentFiles
|
|
||||||
|
|
||||||
- 类型： `string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Client Root Component 文件路径。
|
|
||||||
|
|
||||||
该 Hook 接收文件绝对路径，或者一个返回路径的函数。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
clientAppRootComponentFiles: '/path/to/RootComponent.vue',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### clientAppSetupFiles
|
|
||||||
|
|
||||||
- 类型： `string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
Client App Setup 文件路径。
|
|
||||||
|
|
||||||
该 Hook 接收文件绝对路径，或者一个返回路径的函数。
|
|
||||||
|
|
||||||
- 示例：
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
clientAppSetupFiles: '/path/to/clientAppSetup.js',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 生命周期 Hooks
|
|
||||||
|
|
||||||
### onInitialized
|
|
||||||
|
|
||||||
- 类型： `(app: App) => void | Promise<void>`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该 Hook 会在 VuePress App 初始化后被立即调用。
|
|
||||||
|
|
||||||
### onPrepared
|
|
||||||
|
|
||||||
- 类型： `(app: App) => void | Promise<void>`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该 Hook 会在 VuePress App 完成文件准备后被立即调用。
|
|
||||||
|
|
||||||
### onGenerated
|
|
||||||
|
|
||||||
- 类型： `(app: App) => void | Promise<void>`
|
|
||||||
|
|
||||||
- 详情：
|
|
||||||
|
|
||||||
该 Hook 会在 VuePress App 完成静态文件生成后被立即调用。
|
|
||||||
@ -1,3 +1 @@
|
|||||||
# 官方插件
|
# 插件
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# active-header-links
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
1
docs/zh/reference/plugin/api.md
Normal file
1
docs/zh/reference/plugin/api.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# 插件API
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# back-to-top
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# container
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# debug
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# docsearch
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# git
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# google-analytics
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# medium-zoom
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# nprogress
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# palette-stylus
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
1
docs/zh/reference/plugin/plugins/access.md
Normal file
1
docs/zh/reference/plugin/plugins/access.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-access
|
||||||
1
docs/zh/reference/plugin/plugins/enums.md
Normal file
1
docs/zh/reference/plugin/plugins/enums.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-enums
|
||||||
1
docs/zh/reference/plugin/plugins/icon.md
Normal file
1
docs/zh/reference/plugin/plugins/icon.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-icon
|
||||||
1
docs/zh/reference/plugin/plugins/jest.md
Normal file
1
docs/zh/reference/plugin/plugins/jest.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-jest
|
||||||
1
docs/zh/reference/plugin/plugins/layout.md
Normal file
1
docs/zh/reference/plugin/plugins/layout.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-layout
|
||||||
1
docs/zh/reference/plugin/plugins/locale.md
Normal file
1
docs/zh/reference/plugin/plugins/locale.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-locale
|
||||||
1
docs/zh/reference/plugin/plugins/model.md
Normal file
1
docs/zh/reference/plugin/plugins/model.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-model
|
||||||
1
docs/zh/reference/plugin/plugins/request.md
Normal file
1
docs/zh/reference/plugin/plugins/request.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-request
|
||||||
1
docs/zh/reference/plugin/plugins/vuex.md
Normal file
1
docs/zh/reference/plugin/plugins/vuex.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# fes-plugin-vuex
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# pwa-popup
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# pwa
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -1,3 +0,0 @@
|
|||||||
# 主题 API
|
|
||||||
|
|
||||||
> TODO
|
|
||||||
@ -54,7 +54,7 @@ export default (api) => {
|
|||||||
});
|
});
|
||||||
|
|
||||||
|
|
||||||
// 把BaseLayout插入到路由配置中，作为跟路由
|
// 把BaseLayout插入到路由配置中，作为根路由
|
||||||
api.modifyRoutes(routes => [
|
api.modifyRoutes(routes => [
|
||||||
{
|
{
|
||||||
path: '/',
|
path: '/',
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user