Skip to content

Commit 8ae1999

Browse files
ulivzulivz
committed
docs: update plugin documentation
1 parent b8ce22c commit 8ae1999

File tree

2 files changed

+82
-65
lines changed

2 files changed

+82
-65
lines changed

‎packages/docs/docs/plugin/README.md

+20-18
Original file line numberDiff line numberDiff line change
@@ -456,23 +456,27 @@ import { SOURCE_DIR } from '@dynamic/constans'
456456
- Type: `Function`
457457
- Default: `undefined`
458458

459-
A function that exports a plain object which will be merged into each page's data object. This function will be invoking once for each page at compile time.
459+
A function used to extend or modify the [$page](../miscellaneous/global-computed.md#page) object. This function will be invoking once for each page at compile time
460460

461461
```js
462462
module.exports = {
463-
extendPageData ({
464-
_filePath, // file's absolute path
465-
_i18n, // access the client global mixins at build time, e.g _i18n.$localePath.
466-
_content, // file's raw content string
467-
_strippedContent, // file's content string without frontmatter
468-
key, // page's unique hash key
469-
frontmatter, // page's frontmatter object
470-
regularPath, // current page's default link (follow the file hierarchy)
471-
path, // current page's permalink
472-
}) {
473-
return {
474-
// ...
475-
}
463+
extendPageData ($page) {
464+
const {
465+
_filePath, // file's absolute path
466+
_i18n, // access the client global mixins at build time, e.g _i18n.$localePath.
467+
_content, // file's raw content string
468+
_strippedContent, // file's content string without frontmatter
469+
key, // page's unique hash key
470+
frontmatter, // page's frontmatter object
471+
regularPath, // current page's default link (follow the file hierarchy)
472+
path, // current page's permalink
473+
} = $page
474+
475+
// 1. Add extra files.
476+
page.xxx = 'xxx'
477+
478+
// 2. Change frontmatter.
479+
frontmatter.sidebar = 'auto'
476480
}
477481
}
478482
```
@@ -485,10 +489,8 @@ e.g.
485489

486490
``` js
487491
module.exports = {
488-
extendPageData ({ content }) {
489-
return {
490-
size: (content.length / 1024).toFixed(2) + 'kb'
491-
}
492+
extendPageData ($page) {
493+
$page.size = ($page.content.length / 1024).toFixed(2) + 'kb'
492494
}
493495
}
494496
```

‎packages/docs/docs/zh/plugin/README.md

+62-47
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ sidebar: auto
1010

1111
Plugins usually add global-level functionality to VuePress. There is no strictly defined scope for a plugin - there are typically several types of plugins:
1212

13-
1. Extend the data generated at compile time. e.g. [@vuepress/plugin-last-updated](https://github.com/vuejs/vuepress/tree/next/packages/@vuepress/plugin-last-updated).
14-
2. Generate extra files before or after compilation. e.g. [@vuepress/plugin-pwa](https://github.com/vuejs/vuepress/tree/next/packages/%40vuepress/plugin-pwa)
15-
3. Add extra pages. e.g. [@vuepress/plugin-i18n-ui](https://github.com/vuejs/vuepress/tree/next/packages/@vuepress/plugin-i18n-ui)
16-
4. Inject global UI. e.g. [@vuepress/plugin-back-to-top](https://github.com/vuejs/vuepress/tree/next/packages/%40vuepress/plugin-back-to-top).
13+
1. Extend the data generated at compile time. e.g. [@vuepress/plugin-last-updated](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-last-updated).
14+
2. Generate extra files before or after compilation. e.g. [@vuepress/plugin-pwa](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/plugin-pwa)
15+
3. Add extra pages. e.g. [@vuepress/plugin-i18n-ui](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-i18n-ui)
16+
4. Inject global UI. e.g. [@vuepress/plugin-back-to-top](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/plugin-back-to-top).
1717

1818
A plugin should export a `plain object`(`#1`). If the plugin needs to take options, it can be a function that exports a plain object(`#2`). The function will be called with the plugin's options as the first argument, along with [context](#plugin-context) which provides some compile-time metadata.
1919

@@ -44,7 +44,7 @@ You can use plugins by doing some configuration at `.vuepress/config.js`:
4444
``` js
4545
module.exports = {
4646
plugins: [
47-
require('./my-plugin.js')
47+
require('./my-plugin.js')
4848
]
4949
}
5050
```
@@ -123,7 +123,7 @@ VuePress also provides a simpler way to use plugins from a dependency:
123123
``` js
124124
module.exports = {
125125
plugins: {
126-
'xxx': { /* options */ }
126+
'xxx': { /* options */ }
127127
}
128128
}
129129
```
@@ -135,7 +135,7 @@ The plugin can be disabled when `false` is explicitly passed as option.
135135

136136
``` js
137137
module.exports = {
138-
plugins: [
138+
plugins: [
139139
[ 'xxx', false ] // disabled.
140140
]
141141
}
@@ -160,11 +160,12 @@ module.exports = {
160160
- Type: `string`
161161
- Default: undefined
162162

163-
The name of the plugin.
163+
The name of the plugin.
164164

165165
Internally, vuepress will use the plugin's package name as the plugin name. When your plugin is a local plugin (i.e. using a pure plugin function directly), please be sure to configure this option, that is good for debug tracking.
166166

167167
```js
168+
// .vuepress/config.js
168169
module.exports = {
169170
plugins: [
170171
[
@@ -177,6 +178,24 @@ module.exports = {
177178
}
178179
```
179180

181+
### plugins
182+
183+
- Type: `array`
184+
- Default: `undefined`
185+
186+
A plug-in can contain multiple plugins like a preset.
187+
188+
189+
```js
190+
// your plugin
191+
module.exports = {
192+
plugins: [
193+
'tag',
194+
'category'
195+
]
196+
}
197+
```
198+
180199
### enabled
181200

182201
- Type: `boolean`
@@ -208,9 +227,9 @@ module.exports = {
208227
```
209228

210229
::: tip
211-
Since VuePress is a Vue-SSR based application, there will be two webpack configurations, `isServer` is used to determine whether the current webpack config is applied to the server or client.
230+
Since VuePress is a Vue-SSR based application, there will be two webpack configurations, `isServer` is used to determine whether the current webpack config is applied to the server or client.
212231

213-
**Also see:**
232+
**Also see:**
214233

215234
- [Vue SSR > Build Configuration](https://ssr.vuejs.org/guide/build-config.html)
216235
:::
@@ -230,7 +249,7 @@ module.exports = {
230249
SW_BASE_URL: JSON.stringify('/')
231250
})
232251
])
233-
}
252+
}
234253
}
235254
```
236255

@@ -270,7 +289,7 @@ We can set aliases via [chainWebpack](chainwebpack):
270289
module.exports = (options, ctx) => ({
271290
chainWebpack (config) {
272291
config.resolve.alias.set('@theme', ctx.themePath)
273-
}
292+
}
274293
})
275294
```
276295

@@ -306,7 +325,7 @@ const path = require('path')
306325

307326
module.exports = (options, ctx) => {
308327
const imagesAssetsPath = path.resolve(ctx.sourceDir, '.vuepress/images')
309-
328+
310329
return {
311330
// For development
312331
enhanceDevServer (app) {
@@ -357,25 +376,25 @@ module.exports = {
357376
.link(true)
358377
.breaks(true)
359378

360-
// Modify the arguments of internal plugin.
379+
// Modify the arguments of internal plugin.
361380
config
362381
.plugin('anchor')
363382
.tap(([options]) => [
364383
Object.assign(options, { permalinkSymbol: '#' })
365384
])
366-
385+
367386
// Add extra markdown-it plugin
368387
config
369388
.plugin('sup')
370389
.add(require('markdown-it-sup'))
371-
372-
// Remove internal plugin
390+
391+
// Remove internal plugin
373392
config.plugins.delete('snippet')
374393
}
375394
}
376395
```
377396

378-
**Also see:**
397+
**Also see:**
379398

380399
- [Internal plugins in VuePress](https://github.com/vuejs/vuepress/blob/next/packages/%40vuepress/core/lib/markdown/index.js)
381400
- [Config plugins](https://github.com/neutrinojs/webpack-chain#config-plugins)
@@ -399,7 +418,7 @@ The file can `export default` a hook function which will work like `.vuepress/en
399418

400419
It's worth mentioning that in order for plugin developers to be able to do more things at compile time, this option also supports dynamic code:
401420

402-
``` js
421+
```js
403422
module.exports = (option, context) => {
404423
return {
405424
enhanceAppFiles: [{
@@ -417,7 +436,7 @@ module.exports = (option, context) => {
417436

418437
Sometimes, you may want to generate some client modules at compile time.
419438

420-
``` js
439+
```js
421440
module.exports = (options, context) => ({
422441
clientDynamicModules() {
423442
return {
@@ -434,34 +453,32 @@ Then you can use this module at client side code by:
434453
import { SOURCE_DIR } from '@dynamic/constans'
435454
```
436455

437-
::: tip Q & A
438-
**Q**: Both `clientDynamicModules` and `enhanceAppFiles` can generate dynamic javascript code during build time, so what is the difference between the two?
439-
440-
**A**: The files generated by `clientDynamicModules` needs to be imported as `@dynamic/xxx` by the consumers themselves. But all the files generated by `enhanceAppFiles` will be loaded automatically when the APP is initialized on the client side.
441-
:::
442-
443456
### extendPageData
444457

445458
- Type: `Function`
446459
- Default: `undefined`
447460

448-
A function that exports a plain object which will be merged into each page's data object. This function will be invoking once for each page at compile time.
461+
A function used to extend or modify the [$page](../miscellaneous/global-computed.md#page) object. This function will be invoking once for each page at compile time
449462

450-
``` js
463+
```js
451464
module.exports = {
452-
extendPageData ({
453-
_filePath, // file's absolute path
454-
_i18n, // access the client global mixins at build time, e.g _i18n.$localePath.
455-
_content, // file's raw content string
456-
_strippedContent, // file's content string without frontmatter
457-
key, // page's unique hash key
458-
frontmatter, // page's frontmatter object
459-
regularPath, // current page's default link (follow the file hierarchy)
460-
path, // current page's permalink
461-
}) {
462-
return {
463-
// ...
464-
}
465+
extendPageData ($page) {
466+
const {
467+
_filePath, // file's absolute path
468+
_i18n, // access the client global mixins at build time, e.g _i18n.$localePath.
469+
_content, // file's raw content string
470+
_strippedContent, // file's content string without frontmatter
471+
key, // page's unique hash key
472+
frontmatter, // page's frontmatter object
473+
regularPath, // current page's default link (follow the file hierarchy)
474+
path, // current page's permalink
475+
} = $page
476+
477+
// 1. Add extra files.
478+
page.xxx = 'xxx'
479+
480+
// 2. Change frontmatter.
481+
frontmatter.sidebar = 'auto'
465482
}
466483
}
467484
```
@@ -474,10 +491,8 @@ e.g.
474491

475492
``` js
476493
module.exports = {
477-
extendPageData ({ content }) {
478-
return {
479-
size: (content.length / 1024).toFixed(2) + 'kb'
480-
}
494+
extendPageData ($page) {
495+
$page.size = ($page.content.length / 1024).toFixed(2) + 'kb'
481496
}
482497
}
483498
```
@@ -533,7 +548,7 @@ Add a page with explicit content:
533548
```js
534549
module.exports = {
535550
async additionalPages () {
536-
const rp = require('request-promise');
551+
const rp = require('request-promise');
537552

538553
// VuePress doesn't have request library built-in
539554
// you need to install it yourself.
@@ -593,7 +608,7 @@ Then, VuePress will automatically inject these components behind the theme conta
593608

594609
## Context
595610

596-
Starting with VuePress 1.x.x, VuePress provides an `AppContext` object that stores all the state of the current app and can be accessed through the plugin API.
611+
Starting with VuePress 1.x.x, VuePress provides an `AppContext` object that stores all the state of the current app and can be accessed through the plugin API.
597612

598613
::: warning Note
599614
Context of each plugin is a isolated context, they just inherit from the same app context.

0 commit comments

Comments
 (0)