Skip to content

Commit 556a23c

Browse files
meteorlxymeteorlxy
committed
feat(plugin-palette): add palette plugin
BREAKING CHANGE: migrate `@vuepress/plugin-palette-stylus` to `@vuepress/plugin-palette`
1 parent 2f2bdb5 commit 556a23c

File tree

21 files changed

+477
-268
lines changed

21 files changed

+477
-268
lines changed

‎README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ The codebase has been completely refactored with TypeScript. Some major changes:
1414
- Extract `@vuepress/client` from `@vuepress/core` package
1515
- Extract `@vuepress/bundler-webpack` from `@vuepress/core` package and migrate to webpack 5
1616
- As webpack is decoupled with core, other bundlers are also possible to be supported
17-
- Extract `@vuepress/plugin-palette-stylus` from `@vuepress/core` package - stylus is no longer the default CSS pre-processor, and the way of styles customization should be determined by theme
17+
- Extract `@vuepress/plugin-palette` from `@vuepress/core` package - stylus is no longer the default CSS pre-processor, and the way of styles customization should be determined by theme
1818

1919
The documentation has not finished yet. For now you can check out the breaking changes list below as migration reference.
2020

@@ -73,9 +73,9 @@ Temporarily record some breaking changes here.
7373

7474
The stylus palette system of Vuepress 1.0 (i.e. `styles/palette.styl` and `styles/index.styl`) will only work in default theme.
7575

76-
To make the stylus palette system reusable, it's extracted to `@vuepress/plugin-palette-stylus`.
76+
To make the palette system reusable, it's extracted to `@vuepress/plugin-palette`.
7777

78-
Theme authors can use their own way for users to configure styles (not be limited with stylus).
78+
Theme authors can use their own way for users to configure styles (not be limited with stylus as VuePress 1.0).
7979

8080
#### Frontmatter
8181

‎docs/.vuepress/configs/sidebar/en.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ export const en: SidebarConfig = {
8181
'/reference/plugin/google-analytics.md',
8282
'/reference/plugin/medium-zoom.md',
8383
'/reference/plugin/nprogress.md',
84-
'/reference/plugin/palette-stylus.md',
84+
'/reference/plugin/palette.md',
8585
'/reference/plugin/pwa.md',
8686
'/reference/plugin/pwa-popup.md',
8787
'/reference/plugin/theme-data.md',

‎docs/.vuepress/configs/sidebar/zh.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ export const zh: SidebarConfig = {
8484
'/zh/reference/plugin/google-analytics.md',
8585
'/zh/reference/plugin/medium-zoom.md',
8686
'/zh/reference/plugin/nprogress.md',
87-
'/zh/reference/plugin/palette-stylus.md',
87+
'/zh/reference/plugin/palette.md',
8888
'/zh/reference/plugin/pwa.md',
8989
'/zh/reference/plugin/pwa-popup.md',
9090
'/zh/reference/plugin/theme-data.md',

‎docs/reference/plugin/palette-stylus.md

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/reference/plugin/palette.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# palette
2+
3+
Provide palette support for your theme.
4+
5+
This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases.
6+
7+
For theme authors, this plugin will help you to provide styles customization for users.
8+
9+
## Palette and Style
10+
11+
This plugin will provide a `@vuepress/plugin-palette/palette` (palette file) and a `@vuepress/plugin-palette/style` (style file) to be imported in your theme styles.
12+
13+
The palette file is used for defining style variables, so it's likely to be imported at the beginning of your theme styles. For example, users can define [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), [SASS variables](https://sass-lang.com/documentation/variables), [LESS variables](http://lesscss.org/features/#variables-feature) or [Stylus variables](https://stylus-lang.com/docs/variables.html) in the palette, and then you can use those variables in your theme styles.
14+
15+
The style file is used for overriding the default styles or adding extra styles, so it's likely to be imported at the end of your theme styles.
16+
17+
## Usage
18+
19+
Use this plugin in your theme, assuming you are using SASS:
20+
21+
```ts
22+
export default {
23+
// ...
24+
plugins: [
25+
[
26+
'@vuepress/plugin-palette',
27+
{ preset: 'sass' },
28+
],
29+
],
30+
}
31+
```
32+
33+
Import the palette and style in the `Layout.vue` of your theme:
34+
35+
```vue
36+
<template>
37+
<h1 class="palette-title">Hello, Palette!</h1>
38+
</template>
39+
40+
<style lang="scss">
41+
/* import variables from palette */
42+
@import '@vuepress/plugin-palette/palette';
43+
44+
/* set default value for variables */
45+
$color: red !default;
46+
47+
/* use variables in your styles */
48+
.palette-title {
49+
color: $color;
50+
}
51+
</style>
52+
53+
<style lang="scss" src="@vuepress/plugin-palette/style"></style>
54+
```
55+
56+
Then users can customize variables in `.vuepress/styles/palette.scss`:
57+
58+
```scss
59+
$color: green;
60+
```
61+
62+
And add extra styles in `.vuepress/styles/index.scss`:
63+
64+
```scss
65+
:root {
66+
scroll-behavior: smooth;
67+
}
68+
```
69+
70+
## Options
71+
72+
### preset
73+
74+
- Type: `'css' | 'sass' | 'less' | 'stylus'`
75+
76+
- Default: `'css'`
77+
78+
- Details:
79+
80+
Set preset for other options.
81+
82+
If you don't need advanced customization of the plugin, it's recommended to only set this option and omit other options.
83+
84+
### userPaletteFile
85+
86+
- Type: `string`
87+
88+
- Default:
89+
- css: `'.vuepress/styles/palette.css'`
90+
- sass: `'.vuepress/styles/palette.scss'`
91+
- less: `'.vuepress/styles/palette.less'`
92+
- stylus: `'.vuepress/styles/palette.styl'`
93+
94+
- Details:
95+
96+
File path of the user palette file, relative to source directory.
97+
98+
The default value depends on the [preset](#preset) option.
99+
100+
The file is where users define style variables, and it's recommended to keep the default file path as a convention.
101+
102+
### tempPaletteFile
103+
104+
- Type: `string`
105+
106+
- Default:
107+
- css: `'styles/palette.css'`
108+
- sass: `'styles/palette.scss'`
109+
- less: `'styles/palette.less'`
110+
- stylus: `'styles/palette.styl'`
111+
112+
- Details:
113+
114+
File path of the generated palette temp file, relative to temp directory.
115+
116+
The default value depends on the [preset](#preset) option.
117+
118+
You should import the palette file via `'@vuepress/plugin-palette/palette'` alias, so you don't need to change this option in most cases.
119+
120+
### userStyleFile
121+
122+
- Type: `string`
123+
124+
- Default:
125+
- css: `'.vuepress/styles/index.css'`
126+
- sass: `'.vuepress/styles/index.scss'`
127+
- less: `'.vuepress/styles/index.less'`
128+
- stylus: `'.vuepress/styles/index.styl'`
129+
130+
- Details:
131+
132+
File path of the user style file, relative to source directory.
133+
134+
The default value depends on the [preset](#preset) option.
135+
136+
The file is where users override default styles or add extra styles, and it's recommended to keep the default file path as a convention.
137+
138+
### tempStyleFile
139+
140+
- Type: `string`
141+
142+
- Default:
143+
- css: `'styles/index.css'`
144+
- sass: `'styles/index.scss'`
145+
- less: `'styles/index.less'`
146+
- stylus: `'styles/index.styl'`
147+
148+
- Details:
149+
150+
File path of the generated style temp file, relative to temp directory.
151+
152+
The default value depends on the [preset](#preset) option.
153+
154+
You should import the style file via `'@vuepress/plugin-palette/style'` alias, so you don't need to change this option in most cases.
155+
156+
### importCode
157+
158+
- Type: `(filePath: string) => string`
159+
160+
- Default:
161+
- css: `` (filePath) => `@import '${filePath}';\n` ``
162+
- sass: `` (filePath) => `@forward '${filePath}';\n` ``
163+
- less: `` (filePath) => `@import '${filePath}';\n` ``
164+
- stylus: `` (filePath) => `@require '${filePath}';\n` ``
165+
166+
- Details:
167+
168+
Function to generate import code.
169+
170+
The default value depends on the [preset](#preset) option.
171+
172+
This option is used for generating [tempPaletteFile](#temppalettefile) and [tempStyleFile](#tempstylefile), and you don't need to change this option in most cases.

‎docs/zh/reference/plugin/palette-stylus.md

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/zh/reference/plugin/palette.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# palette
2+
3+
为你的主题提供调色板功能。
4+
5+
该插件主要用于开发主题，并且已经集成到默认主题中。大部分情况下你不需要直接使用它。
6+
7+
对于主题作者，该插件可以帮助你提供用户自定义样式的能力。
8+
9+
## 调色板和样式
10+
11+
该插件会提供一个 `@vuepress/plugin-palette/palette` （调色板文件）和一个 `@vuepress/plugin-palette/style` （样式文件），用于在你的主题样式中引入。
12+
13+
调色板文件用于定义样式变量，因此它一般会在你主题样式的开头引入。举例来说，用户可以在调色板中定义 [CSS 变量](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) 、 [SASS 变量](https://sass-lang.com/documentation/variables) 、 [LESS 变量](http://lesscss.org/features/#variables-feature) 或 [Stylus 变量](https://stylus-lang.com/docs/variables.html) ，然后你可以在你的主题样式中使用这些变量。
14+
15+
样式文件用于覆盖默认样式或添加额外样式，因此它一般会在你主题样式的末尾引入。
16+
17+
## 使用
18+
19+
在你的主题中使用该插件，假设你使用 SASS 作为 CSS 预处理器：
20+
21+
```ts
22+
export default {
23+
// ...
24+
plugins: [
25+
[
26+
'@vuepress/plugin-palette',
27+
{ preset: 'sass' },
28+
],
29+
],
30+
}
31+
```
32+
33+
在你主题的 `Layout.vue` 中引入调色板和样式：
34+
35+
```vue
36+
<template>
37+
<h1 class="palette-title">你好，调色板！</h1>
38+
</template>
39+
40+
<style lang="scss">
41+
/* 从调色板中引入变量 */
42+
@import '@vuepress/plugin-palette/palette';
43+
44+
/* 设置变量的默认值 */
45+
$color: red !default;
46+
47+
/* 在你的样式中使用变量 */
48+
.palette-title {
49+
color: $color;
50+
}
51+
</style>
52+
53+
<style lang="scss" src="@vuepress/plugin-palette/style"></style>
54+
```
55+
56+
然后，用户就可以在 `.vuepress/styles/palette.scss` 中自定义变量：
57+
58+
```scss
59+
$color: green;
60+
```
61+
62+
并在 `.vuepress/styles/index.scss` 中添加额外样式：
63+
64+
```scss
65+
:root {
66+
scroll-behavior: smooth;
67+
}
68+
```
69+
70+
## 配置项
71+
72+
### preset
73+
74+
- 类型： `'css' | 'sass' | 'less' | 'stylus'`
75+
76+
- 默认值： `'css'`
77+
78+
- 详情：
79+
80+
设置其他选项的预设。
81+
82+
如果你没有对该插件进行进阶定制化的需要，建议只设置该配置项并忽略其他选项。
83+
84+
### userPaletteFile
85+
86+
- 类型： `string`
87+
88+
- 默认值：
89+
- css: `'.vuepress/styles/palette.css'`
90+
- sass: `'.vuepress/styles/palette.scss'`
91+
- less: `'.vuepress/styles/palette.less'`
92+
- stylus: `'.vuepress/styles/palette.styl'`
93+
94+
- 详情：
95+
96+
用户调色板文件的路径，是针对源文件目录的相对路径。
97+
98+
默认值依赖于 [preset](#preset) 配置项。
99+
100+
该文件用于用户定义样式变量，建议保持默认值作为约定的文件路径。
101+
102+
### tempPaletteFile
103+
104+
- 类型： `string`
105+
106+
- 默认值：
107+
- css: `'styles/palette.css'`
108+
- sass: `'styles/palette.scss'`
109+
- less: `'styles/palette.less'`
110+
- stylus: `'styles/palette.styl'`
111+
112+
- 详情：
113+
114+
生成的调色板临时文件的路径，是针对临时文件文件目录的相对路径。
115+
116+
默认值依赖于 [preset](#preset) 配置项。
117+
118+
你应该使用 `'@vuepress/plugin-palette/palette'` 别名来引入调色板文件，因此在绝大多数情况下你不需要修改该配置项。
119+
120+
### userStyleFile
121+
122+
- 类型： `string`
123+
124+
- 默认值：
125+
- css: `'.vuepress/styles/index.css'`
126+
- sass: `'.vuepress/styles/index.scss'`
127+
- less: `'.vuepress/styles/index.less'`
128+
- stylus: `'.vuepress/styles/index.styl'`
129+
130+
- 详情：
131+
132+
用户样式文件的路径，是针对源文件目录的相对路径。
133+
134+
默认值依赖于 [preset](#preset) 配置项。
135+
136+
该文件用于用户覆盖默认样式和添加额外样式，建议保持默认值作为约定的文件路径。
137+
138+
### tempStyleFile
139+
140+
- 类型： `string`
141+
142+
- 默认值：
143+
- css: `'styles/index.css'`
144+
- sass: `'styles/index.scss'`
145+
- less: `'styles/index.less'`
146+
- stylus: `'styles/index.styl'`
147+
148+
- 详情：
149+
150+
生成的样式临时文件的路径，是针对临时文件文件目录的相对路径。
151+
152+
默认值依赖于 [preset](#preset) 配置项。
153+
154+
你应该使用 `'@vuepress/plugin-palette/style'` 别名来引入样式文件，因此在绝大多数情况下你不需要修改该配置项。
155+
156+
### importCode
157+
158+
- 类型： `(filePath: string) => string`
159+
160+
- 默认值：
161+
- css: `` (filePath) => `@import '${filePath}';\n` ``
162+
- sass: `` (filePath) => `@forward '${filePath}';\n` ``
163+
- less: `` (filePath) => `@import '${filePath}';\n` ``
164+
- stylus: `` (filePath) => `@require '${filePath}';\n` ``
165+
166+
- 详情：
167+
168+
用于生成引入代码的函数。
169+
170+
默认值依赖于 [preset](#preset) 配置项。
171+
172+
该配置项用于生成 [tempPaletteFile](#temppalettefile) 和 [tempStyleFile](#tempstylefile) ，在绝大多数情况下你不需要修改该配置项。

0 commit comments

Comments
 (0)