sidebar |
---|
auto |
The design concepts of VuePress 1.x are mainly reflected in the following aspects:
- Pluggable.
- Convention over configuration.
- Reasonable priority management.
VuePress 1.0 has been rewritten extensively, and the most important one is the introduction of the Plugin API. What are the benefits of plugins?
With plugins, we can implement many of the core functions with plugins, and you can see many built-in plugins here that cover many of the core functions of VuePress, which used to blend in all parts of the code base, but now they鈥檙e clear at a glance.
In the past, when we came across some less common requirements, we had some doubts: if we wanted to not support it, VuePress usage scenarios were limited; but if we wanted to support it, we had to write it into the core code base and set up a separate configuration API for it. For the maintainers, apart from not conducive to long-term maintenance, this sometimes makes us feel exhausted. We must think of some better solutions. Yes, this is plugin.
Yes, your configuration file is also a plugin, so you can use the Plugin API directly without having to create a new plugin for it and import it in the configuration.
::: tip
The options supported by .vuepress/config.js
are actually based on the plugin options and add some specific options.
:::
The root configuration file of the theme is also a plugin.
::: tip
As with .vuepress/config.js
, the options supported by theme/index.js
are based on the plugin options and add some specific options. Using a graph to express their relationship:
In VuePress, you have the ability to apply some plugins in a plugin:
// vuepress-plugin-xxx
module.exports = {
plugins: [
'a', 'b', 'c'
]
}
VuePress 1.0 begin to introduce some conventions to reduce the user鈥檚 excessive configuration pressure, the most intuitive manifestation of this is the conventions for the document directory structure and the theme directory structure.
In the future, we may combine community feedback to introduce more agreements. Let鈥檚 wait and see.
Senior users have found that both theme developers and regular users have the ability to customize global palettes
, styles
, templates
and plugins
, so how do they work together?
For templates/*
, follow the certain loading priority. Taking templates/ssr.html
as an example:
@flowstart cond1=>condition: User鈥檚 ssr.html exists? cond2=>condition: Theme鈥檚 ssr.html exists? stage1=>operation: Using user鈥檚 ssr.html stage2=>operation: Using theme鈥檚 ssr.html stage3=>operation: Using default ssr.html
cond1(no, right)->cond2(no)->stage3 cond1(yes, bottom)->stage1 cond2(yes, bottom)->stage2 @flowend
::: warning Note
When customizing templates/ssr.html
, or templates/dev.html
, it鈥檚 best to edit it on the basis of the default template files, otherwise it may cause a build failure.
:::
For palette.styl
, index.styl
and plugins
, follow the principles of overriding:
User鈥檚 styles/palette.styl
has a higher priority than the theme鈥檚 styles/palette.styl
, so the theme can define its own palette and the user can tweak it. For example:
// theme/styles/palette.styl
$accentColor = #0f0
// .vuepress/styles/palette.styl
$accentColor = #f00
So the final value of $accentColor
is #f00
.
Both the user鈥檚 styles/index.styl
and the theme鈥檚 styles/index.styl
are generated into the final CSS
file, but the user鈥檚 style is generated later and therefore has higher priority. For example:
// theme/styles/index.styl
.content
font-size 14px
// .vuepress/styles/index.styl
.content
font-size 15px
The final generated CSS is as follows:
/* theme/styles/index.styl */
.content {
font-size: 14px;
}
/* .vuepress/styles/index.styl */
.content {
font-size: 15px;
}
Since all plugins with the same name can be applied ONLY once by default, users can override the default options for plugins in theme. For example:
// theme/index.js
module.exports = {
plugins: [
'vuepress-plugin-xxx',
{ name: 'foo' }
]
}
// .vuepress/config.js
module.exports = {
plugins: [
'vuepress-plugin-xxx',
{ name: 'bar' }
]
}
Then the final value of name
option will be bar
.
With the goal of decoupling, we were able to separate VuePress into the following two libraries by introducing monorepo:
- @vuepress/core锛欼ncluding the core implementation of
dev
,build
andPlugin API
; - @vuepress/theme-default锛歍he default theme you see now.
Of course, for most users, you don鈥檛 need to worry about these three libraries. The VuePress package has already assembled them together, so you can use VuePress like 0.x
.