From e2253c2afb69e8537db372bfd9e90defd3d5d47b Mon Sep 17 00:00:00 2001 From: ULIVZ <472590061@qq.com> Date: Sat, 29 Sep 2018 01:47:13 +0800 Subject: [PATCH] refactor($core): clarify palette.styl and style.styl --- packages/@vuepress/core/lib/app/app.js | 3 - .../core/lib/internal-plugins/overrideCSS.js | 69 ------------------- .../lib/internal-plugins/palette/index.js | 55 +++++++++++++++ .../core/lib/internal-plugins/style/client.js | 4 ++ .../core/lib/internal-plugins/style/index.js | 33 +++++++++ .../@vuepress/core/lib/prepare/AppContext.js | 3 +- .../docs/docs/default-theme-config/README.md | 37 ++++------ packages/docs/docs/faq/README.md | 18 +++++ 8 files changed, 125 insertions(+), 97 deletions(-) delete mode 100644 packages/@vuepress/core/lib/internal-plugins/overrideCSS.js create mode 100644 packages/@vuepress/core/lib/internal-plugins/palette/index.js create mode 100644 packages/@vuepress/core/lib/internal-plugins/style/client.js create mode 100644 packages/@vuepress/core/lib/internal-plugins/style/index.js create mode 100644 packages/docs/docs/faq/README.md diff --git a/packages/@vuepress/core/lib/app/app.js b/packages/@vuepress/core/lib/app/app.js index b379fff4a9..87300ebdc3 100644 --- a/packages/@vuepress/core/lib/app/app.js +++ b/packages/@vuepress/core/lib/app/app.js @@ -9,9 +9,6 @@ import globalUIComponents from '@internal/global-ui' import ClientComputedMixin from '@transform/ClientComputedMixin' import Store from './Store' -// generated from user config -import('@temp/style.styl') - // built-in components import Content from './components/Content' import OutboundLink from './components/OutboundLink.vue' diff --git a/packages/@vuepress/core/lib/internal-plugins/overrideCSS.js b/packages/@vuepress/core/lib/internal-plugins/overrideCSS.js deleted file mode 100644 index 597e74710e..0000000000 --- a/packages/@vuepress/core/lib/internal-plugins/overrideCSS.js +++ /dev/null @@ -1,69 +0,0 @@ -const path = require('path') -const { - fs, logger, chalk, - datatypes: { - isPlainObject, - assertTypes, - isString - } -} = require('@vuepress/shared-utils') - -module.exports = (options, context) => ({ - name: '@vuepress/internal-override-css', - - async ready () { - const { sourceDir, writeTemp } = context - - const overridePath = path.resolve(sourceDir, '.vuepress/override.styl') - const hasUserOverride = fs.existsSync(overridePath) - - if (hasUserOverride) { - logger.tip(`${chalk.magenta('override.styl')} has been deprecated from v1.0.0, using ${chalk.cyan('config.palette')} instead.\n`) - } - - // palette API. - const themePalette = context.themePalette - const { palette: userPalette } = context.siteConfig - const themePaletteContent = resolvePaletteContent(themePalette) - const userPaletteContent = resolvePaletteContent(userPalette) - // user's palette can override theme's palette. - const paletteContent = themePaletteContent + userPaletteContent - await writeTemp('palette.styl', paletteContent) - - // style.styl API. - const stylePath = path.resolve(sourceDir, '.vuepress/style.styl').replace(/[\\]+/g, '/') - const hasUserStyle = fs.existsSync(stylePath) - await writeTemp('style.styl', hasUserStyle ? `@import(${JSON.stringify(stylePath)})` : ``) - - // Temporary tip, will be removed at next release. - if (hasUserOverride && !hasUserStyle) { - logger.tip( - `${chalk.magenta('override.styl')} has been split into 2 APIs, we recommend you upgrade to continue.\n` + - ` See: ${chalk.magenta('https://vuepress.vuejs.org/default-theme-config/#simple-css-override')}` - ) - } - } -}) - -function resolvePaletteContent (palette) { - const { valid, warnMsg } = assertTypes(palette, [String, Object]) - if (!valid) { - if (palette !== undefined) { - logger.warn( - `[vuepress] Invalid value for "palette": ${warnMsg}` - ) - } - return '' - } - - if (isString(palette)) { - if (fs.existsSync(palette)) { - return `@import(${JSON.stringify(palette)})\n` - } - return '' - } else if (isPlainObject(palette)) { - return Object.keys(palette).map(variableName => { - return `${variableName} = ${palette[variableName]}` - }).join('\n') + '\n' - } -} diff --git a/packages/@vuepress/core/lib/internal-plugins/palette/index.js b/packages/@vuepress/core/lib/internal-plugins/palette/index.js new file mode 100644 index 0000000000..67553d7bc5 --- /dev/null +++ b/packages/@vuepress/core/lib/internal-plugins/palette/index.js @@ -0,0 +1,55 @@ +const { + fs, logger, + datatypes: { + isPlainObject, + assertTypes, + isString + } +} = require('@vuepress/shared-utils') + +module.exports = (options, ctx) => ({ + name: '@vuepress/internal-palette', + + async ready () { + const { writeTemp } = ctx + + const themePalette = ctx.themePalette + const { palette: userPalette } = ctx.siteConfig + const themePaletteContent = resolvePaletteContent(themePalette) + const userPaletteContent = resolvePaletteContent(userPalette) + + // user's palette can override theme's palette. + const paletteContent = themePaletteContent + userPaletteContent + console.log(paletteContent) + await writeTemp('palette.styl', paletteContent) + } +}) + +/** + * resolve palette content + * @param {string|object} palette + * @returns {string} + */ + +function resolvePaletteContent (palette) { + const { valid, warnMsg } = assertTypes(palette, [String, Object]) + if (!valid) { + if (palette !== undefined) { + logger.warn( + `[vuepress] Invalid value for "palette": ${warnMsg}` + ) + } + return '' + } + + if (isString(palette)) { + if (fs.existsSync(palette)) { + return `@import(${JSON.stringify(palette)})\n` + } + return '' + } else if (isPlainObject(palette)) { + return Object.keys(palette).map(variableName => { + return `${variableName} = ${palette[variableName]}` + }).join('\n') + '\n' + } +} diff --git a/packages/@vuepress/core/lib/internal-plugins/style/client.js b/packages/@vuepress/core/lib/internal-plugins/style/client.js new file mode 100644 index 0000000000..ac002808df --- /dev/null +++ b/packages/@vuepress/core/lib/internal-plugins/style/client.js @@ -0,0 +1,4 @@ +// generated from user config +import('@temp/style.styl') + +window.__VUEPRESS_STYLE_STYLE_LOADED__ = true diff --git a/packages/@vuepress/core/lib/internal-plugins/style/index.js b/packages/@vuepress/core/lib/internal-plugins/style/index.js new file mode 100644 index 0000000000..775466ebe8 --- /dev/null +++ b/packages/@vuepress/core/lib/internal-plugins/style/index.js @@ -0,0 +1,33 @@ +const path = require('path') +const { fs, logger, chalk } = require('@vuepress/shared-utils') + +module.exports = (options, context) => ({ + name: '@vuepress/internal-style', + + enhanceAppFiles: [path.resolve(__dirname, 'client.js')], + + async ready () { + const { sourceDir, writeTemp } = context + + const overridePath = path.resolve(sourceDir, '.vuepress/override.styl') + const hasUserOverride = fs.existsSync(overridePath) + + if (hasUserOverride) { + logger.tip(`${chalk.magenta('override.styl')} has been deprecated from v1.0.0, using ${chalk.cyan('config.palette')} instead.\n`) + } + + // style.styl API. + const stylePath = path.resolve(sourceDir, '.vuepress/style.styl').replace(/[\\]+/g, '/') + const hasUserStyle = fs.existsSync(stylePath) + await writeTemp('style.styl', hasUserStyle ? `@import(${JSON.stringify(stylePath)})` : ``) + + // Temporary tip, will be removed at next release. + if (hasUserOverride && !hasUserStyle) { + logger.tip( + `${chalk.magenta('override.styl')} has been split into 2 APIs, we recommend you upgrade to continue.\n` + + ` See: ${chalk.magenta('https://vuepress.vuejs.org/default-theme-config/#simple-css-override')}` + ) + } + } +}) + diff --git a/packages/@vuepress/core/lib/prepare/AppContext.js b/packages/@vuepress/core/lib/prepare/AppContext.js index e269385d7e..0733514051 100644 --- a/packages/@vuepress/core/lib/prepare/AppContext.js +++ b/packages/@vuepress/core/lib/prepare/AppContext.js @@ -111,7 +111,8 @@ module.exports = class AppContext { .use(require('../internal-plugins/routes')) .use(require('../internal-plugins/rootMixins')) .use(require('../internal-plugins/enhanceApp')) - .use(require('../internal-plugins/overrideCSS')) + .use(require('../internal-plugins/palette')) + .use(require('../internal-plugins/style')) .use(require('../internal-plugins/layoutComponents')) .use(require('../internal-plugins/pageComponents')) .use(require('../internal-plugins/transformModule')) diff --git a/packages/docs/docs/default-theme-config/README.md b/packages/docs/docs/default-theme-config/README.md index f05425ab18..e00a6bf5cd 100644 --- a/packages/docs/docs/default-theme-config/README.md +++ b/packages/docs/docs/default-theme-config/README.md @@ -436,9 +436,9 @@ editLink: false --- ``` -## Simple CSS Override +## Simple Color Variables Override -If you wish to apply simple overrides to the styling of the default theme, you can create an `.vuepress/override.styl` file. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well. +If you wish to apply simple color overrides to the styling of the default theme, you can create an `.vuepress/palette.styl` file. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well. There are a few color variables you can tweak: @@ -450,34 +450,23 @@ $borderColor = #eaecef $codeBgColor = #282c34 ``` -### Existing issues - -In order to override the default variables mentioned above, `override.styl` will be imported at the end of the `config.styl` in default theme, and this file will be used by multiple files, so once you wrote styles here, your style would be duplicated by multiple times. See [#637](https://github.com/vuejs/vuepress/issues/637). - -### Migrate your styles to `style.styl` - -In fact, The `stylus constants override` should be completed before all Stylus files are compiled; and the `user's additional CSS styles` should be generated at the end of the final style file. Therefore, these two duties should not be completed by the same stylus file. +::: danger Note +You should ONLY write color variables in this file. since `palette.styl` will be imported at the end of the root stylus config file, as a config, it will be used by multiple files, so once you wrote styles here, your style would be duplicated by multiple times. +::: -Start from `0.12.0`, we split `override.styl` into two APIs: `override.styl` and `style.styl`. If you wrote styles at `override.styl` in the past, e.g. +## Simple CSS Override -``` stylus -// .vuepress/override.styl -$textColor = red // stylus constants override. +VuePress provides a convenient way to add extra styles. you can create an `.vuepress/style.styl` file for that: -#my-style {} // your extra styles. +```stylus +content { + font-size 30px +} ``` -You'll need to separate the style part to `style.styl`: - -``` stylus -// .vuepress/override.styl, SHOULD ONLY contain "stylus constants override". -$textColor = red -``` +**Also see:** -``` stylus -// .vuepress/style.styl, your extra styles. -#my-style {} -``` +- [FAQ > Why can't `palette.styl` and `style.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-style-styl-merge-into-one-api) ## Custom Page Class diff --git a/packages/docs/docs/faq/README.md b/packages/docs/docs/faq/README.md new file mode 100644 index 0000000000..bbea7b9700 --- /dev/null +++ b/packages/docs/docs/faq/README.md @@ -0,0 +1,18 @@ +# FAQ + +## Why can't `palette.styl` and `style.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 applied to the global. But for `style.styl`. its job is to override the $default style. 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 is used to describe the compiler's compilation order as follows: + +``` + $palette.styl + + ↓ ↓ ↓ + + $default styles + + ↓ ↓ ↓ + + $style.styl +``` +