提交 5c1e7a48 编写于 作者: S Sun Haoran 提交者: meteorlxy

docs: refine plugin documentation (#2053)

上级 3935bcef
# Plugin # Plugin
Plugins generally add global-level functionality to VuePress. There is no strictly defined scope for a plugin - there are typically several types of plugins: Plugins generally add global-level functionality to VuePress. There is no strictly defined scope for a plugin. You can find out more plugins at [Awesome VuePress](https://github.com/vuepressjs/awesome-vuepress#plugins).
## Examples
There are typically several types of plugins:
1. Extend the page’s metadata generated at compile time. For example [@vuepress/plugin-last-updated](./official/plugin-last-updated.md); 1. Extend the page’s metadata generated at compile time. For example [@vuepress/plugin-last-updated](./official/plugin-last-updated.md);
2. Generate extra files before or after compilation. For example [@vuepress/plugin-pwa](./official/plugin-pwa.md); 2. Generate extra files before or after compilation. For example [@vuepress/plugin-pwa](./official/plugin-pwa.md);
...@@ -9,6 +13,25 @@ Plugins generally add global-level functionality to VuePress. There is no strict ...@@ -9,6 +13,25 @@ Plugins generally add global-level functionality to VuePress. There is no strict
Here is also a little slightly complicated plugin example [@vuepress/plugin-blog](https://vuepress-plugin-blog.ulivz.com) that uses compile-time metadata to generate some dynamic modules and initialize them on the client-side by using `enhanceAppFiles`. Here is also a little slightly complicated plugin example [@vuepress/plugin-blog](https://vuepress-plugin-blog.ulivz.com) that uses compile-time metadata to generate some dynamic modules and initialize them on the client-side by using `enhanceAppFiles`.
## Out of the Box
To keep things at a minimum, not all of the official plugins are shipped with VuePress. Here is the list of plugins that are pre-installed in the VuePress and the default theme, **plugins that are not in the list below need to be installed manually**(e.g. [@vuepress/plugin-back-to-top](./official/plugin-back-to-top.md)).
### Plugins that come with VuePress
- [@vuepress/plugin-last-updated](./official/plugin-last-updated.md)
- [@vuepress/plugin-register-components](./official/plugin-register-components.md)
### Plugins that come with the defualt theme
- [@vuepress/plugin-active-header-links](./official/plugin-active-header-links.md)
- [@vuepress/plugin-nprogress](./official/plugin-nprogress.md)
- [@vuepress/plugin-search](./official/plugin-search.md)
- [vuepress-plugin-container](https://vuepress.github.io/plugins/container/)
- [vuepress-plugin-smooth-scroll](https://vuepress.github.io/plugins/smooth-scroll/)
## Architecture
The architecture of the whole plugin system is as follows: The architecture of the whole plugin system is as follows:
![Architecture of VuePress](/architecture.png) ![Architecture of VuePress](/architecture.png)
...@@ -23,12 +23,12 @@ module.exports = { ...@@ -23,12 +23,12 @@ module.exports = {
``` ```
### Passing Options ### Passing Options
```javascript ```javascript
module.exports = { module.exports = {
plugins: ['@vuepress/active-header-links', { plugins: ['@vuepress/active-header-links', {
sidebarLinkSelector: '.sidebar-link', sidebarLinkSelector: '.sidebar-link',
headerAnchorSelector: '.header-anchor', headerAnchorSelector: '.header-anchor'
headerTopOffset: 120
}] }]
} }
``` ```
...@@ -44,4 +44,3 @@ module.exports = { ...@@ -44,4 +44,3 @@ module.exports = {
- Type: `string` - Type: `string`
- Default: `.header-anchor` - Default: `.header-anchor`
# 插件 # 插件
插件通常会为 VuePress 添加全局功能。插件的范围没有限制——一般有下面几种: 插件通常会为 VuePress 添加全局功能。插件的范围没有限制。你可以在 [Awesome VuePress](https://github.com/vuepressjs/awesome-vuepress#plugins) 中找到更多的插件。
## 样例
以下是几种比较常见的插件:
1. 拓展在编译期生成的页面元数据,如:[@vuepress/plugin-last-updated](./official/plugin-last-updated.md) 1. 拓展在编译期生成的页面元数据,如:[@vuepress/plugin-last-updated](./official/plugin-last-updated.md)
2. 在编译前后生成额外的文件,如:[@vuepress/plugin-pwa](./official/plugin-pwa.md) 2. 在编译前后生成额外的文件,如:[@vuepress/plugin-pwa](./official/plugin-pwa.md)
3. 注入全局的 UI, 如:[@vuepress/plugin-back-to-top](./official/plugin-back-to-top.md); 3. 注入全局的 UI, 如:[@vuepress/plugin-back-to-top](./official/plugin-back-to-top.md);
4. 拓展 CLI 的指令,如 [vuepress-plugin-export](https://github.com/ulivz/vuepress-plugin-export) 4. 拓展 CLI 的指令,如:[vuepress-plugin-export](https://github.com/ulivz/vuepress-plugin-export)
这里也有一个略微复杂的插件案例 [@vuepress/plugin-blog](https://vuepress-plugin-blog.ulivz.com),其使用了编译器的元数据来生成了一些动态模块,并在客户端使用 `enhanceAppFiles` 来初始化他们。
## 开箱即用
为了让项目尽可能地简洁,并非所有官方插件都会随着 VuePress 一同安装。以下是一些随着 VuePress 和默认主题一同安装的插件,**没有出现在下表中的插件需要手动安装**(比如:[@vuepress/plugin-back-to-top](./official/plugin-back-to-top.md))。
### VuePress 自带的插件
- [@vuepress/plugin-last-updated](./official/plugin-last-updated.md)
- [@vuepress/plugin-register-components](./official/plugin-register-components.md)
### 默认主题自带的插件
- [@vuepress/plugin-active-header-links](./official/plugin-active-header-links.md)
- [@vuepress/plugin-nprogress](./official/plugin-nprogress.md)
- [@vuepress/plugin-search](./official/plugin-search.md)
- [vuepress-plugin-container](https://vuepress.github.io/zh/plugins/container/)
- [vuepress-plugin-smooth-scroll](https://vuepress.github.io/zh/plugins/smooth-scroll/)
这里也有一个略微复杂的插件案例 [@vuepress/plugin-blog](https://vuepress-plugin-blog.ulivz.com), 其使用了编译器的元数据来生成了一些动态模块,并在客户端使用 `enhanceAppFiles` 来初始化他们。 ## 架构
整个插件系统的架构如下: 整个插件系统的架构如下:
......
...@@ -22,6 +22,17 @@ module.exports = { ...@@ -22,6 +22,17 @@ module.exports = {
} }
``` ```
### 配置选项
```javascript
module.exports = {
plugins: ['@vuepress/active-header-links', {
sidebarLinkSelector: '.sidebar-link',
headerAnchorSelector: '.header-anchor'
}]
}
```
## 选项 ## 选项
### sidebarLinkSelector ### sidebarLinkSelector
......
...@@ -16,8 +16,6 @@ yarn add -D @vuepress/plugin-medium-zoom ...@@ -16,8 +16,6 @@ yarn add -D @vuepress/plugin-medium-zoom
## 使用 ## 使用
## Usage
**简单使用**: **简单使用**:
```javascript ```javascript
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册