Skip to content

Commit 0ed90d2

Browse files
ulivzulivz
committedOct 7, 2018
docs: add 'Design Concepts of VuePress 1.x'
·
v1.9.10v1.0.0-alpha.6
1 parent 865b53e commit 0ed90d2

File tree

2 files changed

+381
-4
lines changed

2 files changed

+381
-4
lines changed
 

‎packages/docs/docs/miscellaneous/design-concepts.md

+190-2
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,197 @@
22
sidebar: auto
33
---
44

5-
# Design Concepts of VuePress 1.0
5+
# Design Concepts of VuePress 1.x
66

7-
- TODO
7+
The design concepts of VuePress 1.x are mainly reflected in the following aspects:
88

9+
1. Pluggable.
10+
2. Convention over configuration.
11+
3. Reasonable priority management.
12+
13+
## Pluggable
14+
15+
VuePress 1.0 has been rewritten extensively, and the most important one is the introduction of the [Plugin API](../plugin/README.md). So what're the benefits of plugins?
16+
17+
### Decoupling
18+
19+
With plugins, we can implement many of the core functions with plugins, and you can see many built-in plugins [here](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/core/lib/internal-plugins) that cover many of the core functions of VuePress, which used to blend in all parts of the code base, but now they're clear at a glance.
20+
21+
### Configuration management
22+
23+
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.
24+
25+
### `.vuepress/config.js` is also a plugin
26+
27+
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.
28+
29+
::: tip
30+
The options supported by `.vuepress/config.js` are actually based on the plugin options and add some specific options.
31+
:::
32+
33+
34+
### `theme/index.js` is also a plugin
35+
36+
The root configuration file of the theme is also a plugin.
37+
38+
::: tip
39+
As with `.vuepress/config.js`, the options supported by `theme/config.js` are based on the plugin options and add some specific options. Using a graph to express their relationship:
40+
41+
<svg viewBox="0 0 2806 912" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
42+
<!-- Generator: Sketch 51 (57462) - http://www.bohemiancoding.com/sketch -->
43+
<desc>Created with Sketch.</desc>
44+
<defs></defs>
45+
<g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
46+
<rect id="Rectangle-3" fill-opacity="0" fill="#FFFFFF" x="0" y="0" width="2806" height="912"></rect>
47+
<circle id="Oval" stroke="#979797" fill="#EC5975" cx="1212.5" cy="455.5" r="355.5"></circle>
48+
<circle id="Oval" stroke="#979797" fill="#937AC4" cx="1592.5" cy="455.5" r="355.5"></circle>
49+
<path d="M1402.5,155.000018 C1501.96722,218.018606 1568,329.058303 1568,455.520781 C1568,581.983259 1501.96722,693.022956 1402.5,756.041544 C1303.03279,693.022977 1237,581.983271 1237,455.520781 C1237,329.058291 1303.03279,218.018585 1402.50003,155 Z" id="Combined-Shape" stroke="#FFFFFF" stroke-width="10" fill="#00BD8C"></path>
50+
<text id=".vuepress/-config.js" font-family="ArialMT, Arial" font-size="60" font-weight="normal" fill="#FFFFFF">
51+
<tspan x="901.101562" y="436">.vuepress/</tspan>
52+
<tspan x="929.446289" y="503">config.js</tspan>
53+
</text>
54+
<text id="Plugin-API" font-family="ArialMT, Arial" font-size="72" font-weight="normal" fill="#FFFFFF">
55+
<tspan x="1302.42773" y="436">Plugin</tspan>
56+
<tspan x="1344.47461" y="516">API</tspan>
57+
</text>
58+
<text id="theme/-index.js" font-family="ArialMT, Arial" font-size="60" font-weight="normal" fill="#FFFFFF">
59+
<tspan x="1662.78613" y="436">theme/</tspan>
60+
<tspan x="1652.78125" y="503">index.js</tspan>
61+
</text>
62+
</g>
63+
</svg>
64+
:::
65+
66+
### Apply plugins in a plugin
67+
68+
In VuePress, you have the ability to apply some plugins in a plugin:
69+
70+
```js
71+
// vuepress-plugin-xxx
72+
module.exports = {
73+
plugins: [
74+
'a', 'b', 'c'
75+
]
76+
}
77+
```
78+
79+
## Convention over configuration.
80+
81+
VuePress 1.0 begin to introduce some conventions to reduce the user's excessive configuration pressure, the most intuitive manifestation of this is the conventions for the [document directory structure](../guide/directory-structure.md) and the [theme directory structure](../theme/README.md#directory-structure).
82+
83+
In the future, we may combine community feedback to introduce more agreements. Let's wait and see.
84+
85+
## Reasonable priority management.
86+
87+
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?
88+
89+
### Loading Priority
90+
91+
For `templates/*`, follow the certain loading priority. Taking `templates/ssr.html` as an example:
92+
93+
@flowstart
94+
cond1=>condition: User's ssr.html
95+
exists?
96+
cond2=>condition: Theme's ssr.html
97+
exists?
98+
stage1=>operation: Using user's ssr.html
99+
stage2=>operation: Using theme's ssr.html
100+
stage3=>operation: Using default ssr.html
101+
102+
cond1(no, right)->cond2(no)->stage3
103+
cond1(yes, bottom)->stage1
104+
cond2(yes, bottom)->stage2
105+
@flowend
106+
107+
::: warning Note
108+
When customizing `templates/ssr.html`, or `templates/dev.html`, it is best to modify it on the basis of the [default template files](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/app/index.dev.html), otherwise it may cause a build failure.
109+
:::
110+
111+
### Overriding
112+
113+
For `palette.styl`, `index.styl` and `plugins`, follow the principles of overriding:
114+
115+
#### palette.styl
116+
117+
User's `styles/palette.styl` has a higher priority than the theme's `styles/palette.styl`, so the theme can define its own palette and the user can tweak it. e.g.
118+
119+
```stylus
120+
// theme/styles/palette.styl
121+
$accentColor = #0f0
122+
```
123+
124+
```stylus
125+
// .vuepress/styles/palette.styl
126+
$accentColor = #f00
127+
```
128+
129+
So the final value of `$accentColor` is `#f00`.
130+
131+
#### index.styl
132+
133+
Both the user's `styles/index.styl` and the theme's `styles/index.styl` are generated into the final `CSS` file, but the user's style is generated later and therefore has higher priority. e.g.
134+
135+
```stylus
136+
// theme/styles/index.styl
137+
.content
138+
font-size 14px
139+
```
140+
141+
```stylus
142+
// .vuepress/styles/index.styl
143+
.content
144+
font-size 15px
145+
```
146+
147+
The final generated CSS is as follows:
148+
149+
```css
150+
/* theme/styles/index.styl */
151+
.content {
152+
font-size: 14px;
153+
}
154+
155+
/* theme/styles/index.styl */
156+
.content {
157+
font-size: 15px;
158+
}
159+
```
160+
161+
#### plugins
162+
163+
Since all plugins with the same name can be applied ONLY once by default, users can override the default options for plugins in theme. e.g.
164+
165+
```js
166+
// theme/index.js
167+
module.exports = {
168+
plugins: [
169+
'@vuepress/i18n-ui',
170+
{ route: '/i18n-page/' }
171+
]
172+
}
173+
```
174+
175+
```js
176+
// .vuepress/config.js
177+
module.exports = {
178+
plugins: [
179+
'@vuepress/i18n-ui',
180+
{ route: '/i18n/' }
181+
]
182+
}
183+
```
184+
185+
Then the final route of i18n UI is `/i18n/`.
186+
187+
188+
## Others
189+
190+
With the goal of decoupling, we were able to separate VuePress into the following libraries by introducing monorepo:
191+
192+
- [@vuepress/cli](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/cli): Management of command line;
193+
- [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core)：Including the core implementation of `dev`, `build` and `Plugin API`;
194+
- [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default)：The default theme you see now.
195+
196+
Of course, for most users, you don't need to care about the three libraries. Package [vuepress](https://www.npmjs.com/search?Q=vuepress) has already assembled the three packages together, so you can use VuePress like `0.x`.
9197

10198

‎packages/docs/docs/zh/miscellaneous/design-concepts.md

+191-2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,195 @@
22
sidebar: auto
33
---
44

5-
# VuePress 1.0 的设计理念
5+
# VuePress 1.x 的设计理念
66

7-
- TODO
7+
VuePress 1.x 的设计理念主要体现在以下几个方面：
8+
9+
1. 插件化
10+
2. 配置大于约定
11+
3. 合理的优先级管理
12+
13+
## 插件化
14+
15+
VuePress 1.0 进行了大范围的重写，其中最重要的就是引入 [Plugin API](../plugin/README.md)，那么插件带来的好处究竟是什么呢？
16+
17+
### 解耦
18+
19+
有了插件，我们可以将很多核心功能用插件来实现，你可以在[这里](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/core/lib/internal-plugins)看到很多内置的插件，这些插件涵盖了很多 VuePress 的核心功能，在以前，它们糅合在代码库的各个地方，但现在，它们一目了然。
20+
21+
### 配置的管理
22+
23+
在过去，当我们遇到一些不太常见的需求时，我们会有一些疑虑：如果我们打算不支持，VuePress 的使用场景也就受到了限制；但如果想要支持它，我们就必须将其写到核心代码库中，并为其单独开设配置的 API。对于维护者来说，除了不利于长久的维护，这有时也会让我们心力交瘁。我们必须想到一些更好的解决办法，没错，这个办法就是插件。
24+
25+
### `.vuepress/config.js` 也是插件
26+
27+
没错，你的配置文件也是一个插件，因此，你可以直接使用插件 API，而不必为此新建一个插件，然后在配置中导入它。
28+
29+
::: tip
30+
`.vuepress/config.js` 所支持的 API，实际上是在插件选项的基础上又新增了一些特定的选项。
31+
:::
32+
33+
### `theme/index.js` 也是插件
34+
35+
主题的根配置文件也是插件。
36+
37+
::: tip
38+
和 `.vuepress/config.js` 一样，`theme/config.js` 所支持的选项，也是在插件选项的基础上，又新增了一些特定的选项。用一张图来表达它们的关系就是：
39+
40+
<svg viewBox="0 0 2806 912" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
41+
<!-- Generator: Sketch 51 (57462) - http://www.bohemiancoding.com/sketch -->
42+
<desc>Created with Sketch.</desc>
43+
<defs></defs>
44+
<g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
45+
<rect id="Rectangle-3" fill-opacity="0" fill="#FFFFFF" x="0" y="0" width="2806" height="912"></rect>
46+
<circle id="Oval" stroke="#979797" fill="#EC5975" cx="1212.5" cy="455.5" r="355.5"></circle>
47+
<circle id="Oval" stroke="#979797" fill="#937AC4" cx="1592.5" cy="455.5" r="355.5"></circle>
48+
<path d="M1402.5,155.000018 C1501.96722,218.018606 1568,329.058303 1568,455.520781 C1568,581.983259 1501.96722,693.022956 1402.5,756.041544 C1303.03279,693.022977 1237,581.983271 1237,455.520781 C1237,329.058291 1303.03279,218.018585 1402.50003,155 Z" id="Combined-Shape" stroke="#FFFFFF" stroke-width="10" fill="#00BD8C"></path>
49+
<text id=".vuepress/-config.js" font-family="ArialMT, Arial" font-size="60" font-weight="normal" fill="#FFFFFF">
50+
<tspan x="901.101562" y="436">.vuepress/</tspan>
51+
<tspan x="929.446289" y="503">config.js</tspan>
52+
</text>
53+
<text id="Plugin-API" font-family="ArialMT, Arial" font-size="72" font-weight="normal" fill="#FFFFFF">
54+
<tspan x="1302.42773" y="436">Plugin</tspan>
55+
<tspan x="1344.47461" y="516">API</tspan>
56+
</text>
57+
<text id="theme/-index.js" font-family="ArialMT, Arial" font-size="60" font-weight="normal" fill="#FFFFFF">
58+
<tspan x="1662.78613" y="436">theme/</tspan>
59+
<tspan x="1652.78125" y="503">index.js</tspan>
60+
</text>
61+
</g>
62+
</svg>
63+
:::
64+
65+
66+
### 在插件中使用插件
67+
68+
在 VuePress 中，你拥有在插件中使用插件的能力：
69+
70+
```js
71+
// vuepress-plugin-xxx
72+
module.exports = {
73+
plugins: [
74+
'a', 'b', 'c'
75+
]
76+
}
77+
```
78+
79+
## 约定大于配置
80+
81+
VuePress 1.0 开始引入一些约定，以减少用户过多的配置压力。对于这一点，最直观的体现是对[文档目录结构](../guide/directory-structure.md)和[主题目录结构](../theme/README.md#directory-structure)的约定。
82+
83+
未来我们可能还会结合社区的反馈来引入更多的约定，让我们拭目以待。
84+
85+
86+
## 合理的优先级管理
87+
88+
资深的 VuePress 用户可能已经发现，主题开发者和普通的文档用户都具有定义全局的 `palette`、`style`、`templates` 和 `plugins` 的能力，那么他们是如何协同工作的呢？
89+
90+
### 加载优先级
91+
92+
`templates/*` 遵循一定的加载优先级，以 `templates/ssr.html` 为例：
93+
94+
@flowstart
95+
cond1=>condition: 用户的 ssr.html
96+
是否存在?
97+
cond2=>condition: 主题的 ssr.html
98+
是否存在?
99+
stage1=>operation: 使用用户的 ssr.html
100+
stage2=>operation: 使用主题的 ssr.html
101+
stage3=>operation: 使用默认的 ssr.html
102+
103+
cond1(no, right)->cond2(no)->stage3
104+
cond1(yes, bottom)->stage1
105+
cond2(yes, bottom)->stage2
106+
@flowend
107+
108+
::: warning 注意
109+
当你想要去自定义 `templates/ssr.html` 或 `templates/dev.html` 时，最好基于 [默认的模板文件](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/app/index.dev.html) 来修改，否则可能会导致构建出错。
110+
:::
111+
112+
### Overriding
113+
114+
对于 `palette.styl`、`index.styl` 和 `plugins`, 遵循 `overriding` 的原则：
115+
116+
#### `palette.styl`
117+
118+
用户的 `styles/palette.styl` 具有比主题的 `styles/palette.styl` 更高的优先级，因此主题可以先预定义一套调色板，而用户又可以根据自身需要修改它。例如：
119+
120+
```stylus
121+
// theme/styles/palette.styl
122+
$accentColor = #0f0
123+
```
124+
125+
```stylus
126+
// .vuepress/styles/palette.styl
127+
$accentColor = #f00
128+
```
129+
130+
`$accentColor` 最终的值是 `#f00`。
131+
132+
#### `index.styl`
133+
134+
用户和主题的 `styles/index.styl` 都会被生成到最终的 CSS 文件中，但是默认情况下，用户的样式会生成在主题的样式后面，因此对于同样的选择器，用户的样式将具有更高的优先级，如：
135+
136+
```stylus
137+
// theme/styles/index.styl
138+
.content
139+
font-size 14px
140+
```
141+
142+
```stylus
143+
// .vuepress/styles/index.styl
144+
.content
145+
font-size 15px
146+
```
147+
148+
最终生成的 CSS 文件如下：
149+
150+
```css
151+
/* theme/styles/index.styl */
152+
.content {
153+
font-size: 14px;
154+
}
155+
156+
/* theme/styles/index.styl */
157+
.content {
158+
font-size: 15px;
159+
}
160+
```
161+
162+
#### `plugins`
163+
164+
由于同名插件默认情况下只能应用一次，因此用户可以修改主题中预置的插件选项的默认值，如：
165+
166+
```js
167+
// theme/index.js
168+
module.exports = {
169+
plugins: [
170+
'@vuepress/i18n-ui',
171+
{ route: '/i18n-page/' }
172+
]
173+
}
174+
```
175+
176+
```js
177+
// .vuepress/config.js
178+
module.exports = {
179+
plugins: [
180+
'@vuepress/i18n-ui',
181+
{ route: '/i18n/' }
182+
]
183+
}
184+
```
185+
186+
i18n UI 最终的路由将是 `/i18n/`.
187+
188+
## 其他
189+
190+
本着解耦的目标，引入 monorepo 后，我们也得以将 VuePress 分离成以下几个库：
191+
192+
- [@vuepress/cli](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/cli): 命令行指令的管理；
193+
- [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core)：包含 dev、build 的核心实现和 Plugin API；
194+
- [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default)：你现在所看到的默认主题。
195+
196+
当然，对于大多数用户来说，你并不需要关心上述三个库，[vuepress](https://www.npmjs.com/search?q=vuepress) 这个包已经将上述三个包组装在一起，你完全可以像 `0.x` 那样使用 VuePress。

0 commit comments

Comments
 (0)
Please sign in to comment.