feat($default-theme): new file-level API: style.styl.

1. Fixed overriding css doesn't work at 0.11.0 (close: #639)

2. Split override.styl into two APIs: override.styl and style.styl, the former will focus on ONLY the style constants override, while the latter will focus on styles override or custom styles. See also: https://vuepress.vuejs.org/default-theme-config/#simple-css-override.

Author: ulivz

docs/.vuepress/override.styl

@@ -419,6 +419,39 @@ $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 will be duplicated by multiple times. See [#637](https://github.com/vuejs/vuepress/issues/637).
+
+In fact, `style constants override` and `styles override` are two things, the former should be executed before any CSS is compiled, while the latter should be generated at the end of the CSS bundle, which has the highest priority. 
+
+### Migrate your styles to `style.styl` <Badge text="0.12.0+"/>
+
+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.
+
+``` stylus
+// override.styl
+$textColor = red // style constants override
+
+#my-style {} // styles override or custom styles.
+```
+
+You'll need to separate the style part to `style.styl`:
+
+``` stylus
+// override.styl
+// SHOULD ONLY focus on style constants override.
+$textColor = red
+```
+
+``` stylus
+// style.styl
+// SHOULD focus on styles override or your custom styles.
+#my-style {}
+```
+
 ## Custom Page Class
 
 Sometimes, you may need to add a unique class for a specific page so that you can target content on that page only in custom CSS. You can add a class to the theme container div with `pageClass` in `YAML front matter`:

docs/default-theme-config/README.md

@@ -8,7 +8,7 @@ import enhanceApp from '@temp/enhanceApp'
 import themeEnhanceApp from '@temp/themeEnhanceApp'
 
 // generated from user config
-import('@temp/override.styl')
+import('@temp/style.styl')
 
 // built-in components
 import Content from './components/Content'

lib/app/app.js

@@ -17,3 +17,5 @@ $MQMobileNarrow = 419px
 
 // code
 $lineNumbersWrapperWidth = 3.5rem
+
+@import '~@temp/override.styl'

lib/default-theme/styles/config.styl

@@ -3,6 +3,8 @@ const fs = require('fs-extra')
 const resolveOptions = require('./resolveOptions')
 const { genRoutesFile, genComponentRegistrationFile } = require('./codegen')
 const { writeTemp, writeEnhanceTemp } = require('./util')
+const logger = require('../util/logger')
+const chalk = require('chalk')
 
 module.exports = async function prepare (sourceDir) {
   // 1. load options
@@ -24,7 +26,19 @@ module.exports = async function prepare (sourceDir) {
   // 4. handle user override
   const overridePath = path.resolve(sourceDir, '.vuepress/override.styl')
   const hasUserOverride = fs.existsSync(overridePath)
-  await writeTemp(`override.styl`, hasUserOverride ? `@import(${JSON.stringify(overridePath)})` : ``)
+  await writeTemp('override.styl', hasUserOverride ? `@import(${JSON.stringify(overridePath)})` : ``)
+
+  const stylePath = path.resolve(sourceDir, '.vuepress/style.styl')
+  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')}`
+    )
+  }
 
   // 5. handle enhanceApp.js
   const enhanceAppPath = path.resolve(sourceDir, '.vuepress/enhanceApp.js')