From c653699553642a12f7e2b21f26a326cfb7fb8fa9 Mon Sep 17 00:00:00 2001 From: "Joaquin (Pato) Decima" Date: Thu, 14 Oct 2021 19:58:06 -0300 Subject: [PATCH 1/3] refactor($core): `palette.styl` to `variables.styl` #2108 --- .../core/lib/client/style/config.styl | 2 +- .../node/internal-plugins/palette/index.js | 40 ++++++++++++------- .../lib/node/internal-plugins/style/index.js | 2 +- 3 files changed, 27 insertions(+), 17 deletions(-) diff --git a/packages/@vuepress/core/lib/client/style/config.styl b/packages/@vuepress/core/lib/client/style/config.styl index 558c4fcc8a..4ac9a2883e 100644 --- a/packages/@vuepress/core/lib/client/style/config.styl +++ b/packages/@vuepress/core/lib/client/style/config.styl @@ -1,4 +1,4 @@ -@require '~@temp/palette.styl' +@require '~@temp/variables.styl' // colors $accentColor ?= #3eaf7c diff --git a/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js b/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js index 49d162ec2e..1dd27d44c8 100644 --- a/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js +++ b/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js @@ -1,5 +1,5 @@ const { - fs, path, + fs, path, logger, datatypes: { isPlainObject } } = require('@vuepress/shared-utils') @@ -17,38 +17,48 @@ module.exports = (options, ctx) => ({ ctx.siteConfig.stylus.import = (ctx.siteConfig.stylus.import || []).concat([configFile]) } - // 2. write palette.styl + // 2. write variables.styl const { sourceDir, writeTemp } = ctx + const themeVariables = path.resolve(ctx.themeAPI.theme.path, 'styles/variables.styl') + const userVariables = path.resolve(sourceDir, '.vuepress/styles/variables.styl') + + // Deprecation const themePalette = path.resolve(ctx.themeAPI.theme.path, 'styles/palette.styl') const userPalette = path.resolve(sourceDir, '.vuepress/styles/palette.styl') - const themePaletteContent = fs.existsSync(themePalette) - ? `@import(${JSON.stringify(themePalette.replace(/[\\]+/g, '/'))})` - : '' + const themeVariablesContent = fs.existsSync(themeVariables) + ? `@import(${JSON.stringify(themeVariables.replace(/[\\]+/g, '/'))})` + : (fs.existsSync(themePalette) + ? `@import(${JSON.stringify(themePalette.replace(/[\\]+/g, '/'))})` + : '') - const userPaletteContent = fs.existsSync(userPalette) - ? `@import(${JSON.stringify(userPalette.replace(/[\\]+/g, '/'))})` - : '' + const userVariablesContent = fs.existsSync(userVariables) + ? `@import(${JSON.stringify(userVariables.replace(/[\\]+/g, '/'))})` + : (fs.existsSync(userPalette) + ? `@import(${JSON.stringify(userPalette.replace(/[\\]+/g, '/'))})` + : '')(fs.existsSync(userPalette) || fs.existsSync(themePalette)) + ? logger.warn('palette.style is deprecation') + : '' const nullComment = '// null' // user's palette can override theme's palette. - let paletteContent = '// Theme\'s Palette\n' - + (themePaletteContent || nullComment) + let variablesContent = '// Theme\'s Palette\n' + + (themeVariablesContent || nullComment) + '\n\n// User\'s Palette\n' - + (userPaletteContent || nullComment) + + (userVariablesContent || nullComment) if (ctx.themeAPI.existsParentTheme) { - const parentThemePalette = path.resolve(ctx.themeAPI.parentTheme.path, 'styles/palette.styl') + const parentThemePalette = path.resolve(ctx.themeAPI.parentTheme.path, 'styles/variables.styl') const parentThemePaletteContent = fs.existsSync(parentThemePalette) ? `@import(${JSON.stringify(parentThemePalette.replace(/[\\]+/g, '/'))})` : '' - paletteContent = '// Parent Theme\'s Palette\n' + variablesContent = '// Parent Theme\'s Palette\n' + (parentThemePaletteContent || nullComment) - + '\n\n' + paletteContent + + '\n\n' + variablesContent } - await writeTemp('palette.styl', paletteContent) + await writeTemp('variables.styl', variablesContent) } }) diff --git a/packages/@vuepress/core/lib/node/internal-plugins/style/index.js b/packages/@vuepress/core/lib/node/internal-plugins/style/index.js index b8a54871e0..1828a918ef 100644 --- a/packages/@vuepress/core/lib/node/internal-plugins/style/index.js +++ b/packages/@vuepress/core/lib/node/internal-plugins/style/index.js @@ -16,7 +16,7 @@ module.exports = (options, ctx) => ({ const hasUserOverride = fs.existsSync(overridePath) if (hasUserOverride) { - logger.tip(`${chalk.magenta('override.styl')} has been deprecated from v1.0.0, using ${chalk.cyan('.vuepress/styles/palette.styl')} instead.\n`) + logger.tip(`${chalk.magenta('override.styl')} has been deprecated from v1.0.0, using ${chalk.cyan('.vuepress/styles/variables.styl')} instead.\n`) } const themeStyle = path.resolve(themeAPI.theme.path, 'styles/index.styl') From 8d2832a1b0363ed80ceb9b93f634d94bc6709e09 Mon Sep 17 00:00:00 2001 From: "Joaquin (Pato) Decima" Date: Thu, 14 Oct 2021 20:00:07 -0300 Subject: [PATCH 2/3] docs: update documentation variables.styl #2108 --- packages/docs/docs/config/README.md | 10 +++++----- packages/docs/docs/faq/README.md | 6 +++--- packages/docs/docs/guide/directory-structure.md | 6 +++--- packages/docs/docs/miscellaneous/design-concepts.md | 10 +++++----- packages/docs/docs/plugin/official/plugin-nprogress.md | 6 +++--- packages/docs/docs/plugin/official/plugin-search.md | 2 +- packages/docs/docs/theme/inheritance.md | 2 +- packages/docs/docs/theme/writing-a-theme.md | 2 +- 8 files changed, 22 insertions(+), 22 deletions(-) diff --git a/packages/docs/docs/config/README.md b/packages/docs/docs/config/README.md index 9400f93d35..e6eaca0386 100644 --- a/packages/docs/docs/config/README.md +++ b/packages/docs/docs/config/README.md @@ -140,9 +140,9 @@ Specify which pattern of files you want to be resolved. ## Styling -### palette.styl +### variables.styl -To apply simple overrides to the styling of the [default preset](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl) or define some variables to use later, you can create a `.vuepress/styles/palette.styl` file. +To apply simple overrides to the styling of the [default preset](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl) or define some variables to use later, you can create a `.vuepress/styles/variables.styl` file. There are some predefined variables you can tweak: @@ -170,7 +170,7 @@ $MQMobileNarrow = 419px ``` ::: danger Note -You should ONLY define variables in this file. Since `palette.styl` will be imported at the end of the root Stylus config file, as a config, several files will use it, so once you wrote styles here, your style would be duplicated by multiple times. +You should ONLY define variables in this file. Since `variables.styl` will be imported at the end of the root Stylus config file, as a config, several files will use it, so once you wrote styles here, your style would be duplicated by multiple times. ::: ### index.styl @@ -184,7 +184,7 @@ VuePress provides a convenient way to add extra styles. You can create a `.vuepr ``` ::: warning -Because of the behavior behind the scenes, in both `palette.styl` and `index.styl`, the normal `.css` style sheets are not allowed to be imported by [@import / @require](https://stylus-lang.com/docs/import.html) from **relative paths**. +Because of the behavior behind the scenes, in both `variables.styl` and `index.styl`, the normal `.css` style sheets are not allowed to be imported by [@import / @require](https://stylus-lang.com/docs/import.html) from **relative paths**. ::: ::: details What if you have to import / require normal `css` style sheets? @@ -215,7 +215,7 @@ As there’s an [alias](../plugin/option-api.html#alias) option out there, using **Also see:** -- [Why can’t `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api) +- [Why can’t `variables.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api) ## Theming diff --git a/packages/docs/docs/faq/README.md b/packages/docs/docs/faq/README.md index b045691045..3e2dc4507e 100644 --- a/packages/docs/docs/faq/README.md +++ b/packages/docs/docs/faq/README.md @@ -4,16 +4,16 @@ sidebar: auto # FAQ -## Why can’t `palette.styl` and `index.styl` merge into one API? +## Why can’t `variables.styl` and `index.styl` merge into one API? -The `palette.styl` is responsible for global color settings. During compilation, theme color constants should be resolved by the preprocessor first and then be applied to the global context. +The `variables.styl` is responsible for global color settings. During compilation, theme color constants should be resolved by the preprocessor first and then be applied to the global context. But for `index.styl`, its job is to override the default styles of application. According to the priority principle of CSS, the later style has a higher priority, so it should be generated at the end of the CSS file. A simple diagram describing the Stylus compiler’s compilation order as follows: @flowstart -stage1=>operation: palette.styl +stage1=>operation: variables.styl stage2=>operation: default app styles stage3=>operation: index.styl diff --git a/packages/docs/docs/guide/directory-structure.md b/packages/docs/docs/guide/directory-structure.md index 9bde09ea4e..5dfdeb182f 100644 --- a/packages/docs/docs/guide/directory-structure.md +++ b/packages/docs/docs/guide/directory-structure.md @@ -14,7 +14,8 @@ VuePress follows the principle of **"Convention is better than configuration"**. │   │   ├── `public` _(**Optional**)_ │   │   ├── `styles` _(**Optional**)_ │   │   │   ├── index.styl -│   │   │   └── palette.styl +│   │   │   └── variables.styl +│   │   │   └── palette.styl _(**Deprecation**)_ │   │   ├── `templates` _(**Optional, Danger Zone**)_ │   │   │   ├── dev.html │   │   │   └── ssr.html @@ -40,7 +41,7 @@ Please note the capitalization of the directory name. - `docs/.vuepress/theme`: Used to store local theme. - `docs/.vuepress/styles`: Stores style related files. - `docs/.vuepress/styles/index.styl`: Automatically applied global style files, generated at the ending of the CSS file, have a higher priority than the default style. -- `docs/.vuepress/styles/palette.styl`: The palette is used to override the default color constants and to set the color constants of Stylus. +- `docs/.vuepress/styles/variables.styl`: The palette is used to override the default color constants and to set the color constants of Stylus. - `docs/.vuepress/public`: Static resource directory. - `docs/.vuepress/templates`: Store HTML template files. - `docs/.vuepress/templates/dev.html`: HTML template file for development environment. @@ -78,4 +79,3 @@ For the above directory structure, the default page routing paths are as follows - [Config](../config/README.md) - [Theme](../theme/) - [Default Theme Config](../theme/default-theme-config.md) - diff --git a/packages/docs/docs/miscellaneous/design-concepts.md b/packages/docs/docs/miscellaneous/design-concepts.md index f07ad651f4..804893d7ea 100644 --- a/packages/docs/docs/miscellaneous/design-concepts.md +++ b/packages/docs/docs/miscellaneous/design-concepts.md @@ -114,19 +114,19 @@ When customizing `templates/ssr.html`, or `templates/dev.html`, it’s best to e ### Overriding -For `palette.styl`, `index.styl` and `plugins`, follow the principles of overriding: +For `variables.styl`, `index.styl` and `plugins`, follow the principles of overriding: -#### palette.styl +#### variables.styl -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. For example: +User’s `styles/variables.styl` has a higher priority than the theme’s `styles/variables.styl`, so the theme can define its own palette and the user can tweak it. For example: ```stylus -// theme/styles/palette.styl +// theme/styles/variables.styl $accentColor = #0f0 ``` ```stylus -// .vuepress/styles/palette.styl +// .vuepress/styles/variables.styl $accentColor = #f00 ``` diff --git a/packages/docs/docs/plugin/official/plugin-nprogress.md b/packages/docs/docs/plugin/official/plugin-nprogress.md index 632aab15e4..02cd72b239 100644 --- a/packages/docs/docs/plugin/official/plugin-nprogress.md +++ b/packages/docs/docs/plugin/official/plugin-nprogress.md @@ -24,12 +24,12 @@ module.exports = { ## Custom color -Set `$nprogressColor` in your __site__ or __theme__ `palette.styl` file to change the color of the progress bar (default is `$accentColor`). +Set `$nprogressColor` in your __site__ or __theme__ `variables.styl` file to change the color of the progress bar (default is `$accentColor`). ```stylus -// .vuepress/styles/palette.styl +// .vuepress/styles/variables.styl // or -// .vuepress/theme/styles/palette.styl +// .vuepress/theme/styles/variables.styl $nprogressColor = red ``` diff --git a/packages/docs/docs/plugin/official/plugin-search.md b/packages/docs/docs/plugin/official/plugin-search.md index f0a6ba9ff8..63ec44c472 100644 --- a/packages/docs/docs/plugin/official/plugin-search.md +++ b/packages/docs/docs/plugin/official/plugin-search.md @@ -106,7 +106,7 @@ Configure the hotkeys which when pressed will focus the search box. Set to an em ### Tweak the default colors. -Since the Search component leverages the built-in palette, you can tweak the default colors via `styles/palette.styl`: +Since the Search component leverages the built-in palette, you can tweak the default colors via `styles/variables.styl`: ```stylus // colors of the searchbox you see now: diff --git a/packages/docs/docs/theme/inheritance.md b/packages/docs/docs/theme/inheritance.md index f18778437d..274ea617a3 100644 --- a/packages/docs/docs/theme/inheritance.md +++ b/packages/docs/docs/theme/inheritance.md @@ -42,7 +42,7 @@ The [file-level conventions](./writing-a-theme.md#directory-structure) are as fo - **Global Components**，that is the Vue components under `theme/global-components`. - **Components**，that is the Vue components under `theme/components`. -- **Global Style and Palette**，that is `index.styl` and `palette.styl` under `theme/styles`. +- **Global Style and Palette**，that is `index.styl` and `variables.styl` under `theme/styles`. - **HTML Template**, that is `dev.html` and `ssr.html` under `theme/templates`. - **Theme-Level App Enhancement File**，that is `theme/enhanceApp.js` diff --git a/packages/docs/docs/theme/writing-a-theme.md b/packages/docs/docs/theme/writing-a-theme.md index 23b29191ee..190636f824 100644 --- a/packages/docs/docs/theme/writing-a-theme.md +++ b/packages/docs/docs/theme/writing-a-theme.md @@ -44,7 +44,7 @@ theme │   └── 404.vue ├── `styles` │   ├── index.styl -│   └── palette.styl +│   └── variables.styl ├── `templates` │   ├── dev.html │   └── ssr.html From 762c999769c135e591e38f33ec45b6773498d715 Mon Sep 17 00:00:00 2001 From: "Joaquin (Pato) Decima" Date: Thu, 14 Oct 2021 20:10:47 -0300 Subject: [PATCH 3/3] fix($core): intermediate value error --- .../core/lib/node/internal-plugins/palette/index.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js b/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js index 1dd27d44c8..22ef41c8cd 100644 --- a/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js +++ b/packages/@vuepress/core/lib/node/internal-plugins/palette/index.js @@ -37,9 +37,11 @@ module.exports = (options, ctx) => ({ ? `@import(${JSON.stringify(userVariables.replace(/[\\]+/g, '/'))})` : (fs.existsSync(userPalette) ? `@import(${JSON.stringify(userPalette.replace(/[\\]+/g, '/'))})` - : '')(fs.existsSync(userPalette) || fs.existsSync(themePalette)) - ? logger.warn('palette.style is deprecation') - : '' + : '') + + fs.existsSync(userPalette) || fs.existsSync(themePalette) + ? logger.warn('palette.style is deprecation') + : '' const nullComment = '// null'