refactor($core): clarify palette.styl and style.styl

Author: ulivz

Diff for: 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 for: packages/@vuepress/core/lib/internal-plugins/overrideCSS.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 for: packages/@vuepress/core/lib/internal-plugins/palette/index.js

@@ -0,0 +1,4 @@
+// generated from user config
+import('@temp/style.styl')
+
+window.__VUEPRESS_STYLE_STYLE_LOADED__ = true

Diff for: packages/@vuepress/core/lib/internal-plugins/style/client.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 for: packages/@vuepress/core/lib/internal-plugins/style/index.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 for: packages/@vuepress/core/lib/prepare/AppContext.js

@@ -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 <Badge text="< 0.12.0" type='error'/>
-
-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` <Badge text="0.12.0+"/>
-
-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 for: packages/docs/docs/default-theme-config/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
+```
+