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
+```
+