feat($core): make palette globally enabled and improve doc

Author: ulivz

packages/@vuepress/core/lib/internal-plugins/palette/index.js

@@ -1,5 +1,5 @@
 const {
-  fs, logger,
+  fs, path, logger,
   datatypes: {
     isPlainObject,
     assertTypes,
@@ -11,15 +11,29 @@ module.exports = (options, ctx) => ({
   name: '@vuepress/internal-palette',
 
   async ready () {
-    const { writeTemp } = ctx
+    // 1. enable config.styl globally.
+    const configFile = path.resolve(__dirname, '../../app/style/config.styl')
+    if (!ctx.siteConfig.stylus) {
+      ctx.siteConfig.stylus = {
+        import: [configFile]
+      }
+    } else if (isPlainObject(ctx.siteConfig.stylus)) {
+      ctx.siteConfig.stylus.import = (ctx.siteConfig.stylus.import || []).concat([configFile])
+    }
+
+    // 2. write palette.styl
+    const { sourceDir, writeTemp } = ctx
 
     const themePalette = ctx.themePalette
     const { palette: userPalette } = ctx.siteConfig
+    const palettePath = path.resolve(sourceDir, '.vuepress/palette.styl')
+
     const themePaletteContent = resolvePaletteContent(themePalette)
     const userPaletteContent = resolvePaletteContent(userPalette)
+    const userPaletteContent2 = resolvePaletteContent(palettePath)
 
     // user's palette can override theme's palette.
-    const paletteContent = themePaletteContent + userPaletteContent
+    const paletteContent = themePaletteContent + userPaletteContent + userPaletteContent2
     await writeTemp('palette.styl', paletteContent)
   }
 })

packages/@vuepress/core/lib/internal-plugins/style/client.js

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

packages/@vuepress/plugin-search/SearchBox.vue

@@ -153,8 +153,6 @@ export default {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .search-box
   display inline-block
   position relative

packages/@vuepress/theme-default/components/AlgoliaSearchBox.vue

@@ -59,8 +59,6 @@ export default {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .algolia-search-wrapper
   & > span
     vertical-align middle

packages/@vuepress/theme-default/components/Badge.vue

@@ -21,8 +21,6 @@ export default {
 </script>
 
 <style lang="stylus" scoped>
-@import '~@app/style/config'
-
 .badge
   display inline-block
   font-size 14px

packages/@vuepress/theme-default/components/DropdownLink.vue

@@ -77,8 +77,6 @@ export default {
 </script>
 
 <style lang="stylus">
-  @import '~@app/style/config'
-
 .dropdown-wrapper
   cursor pointer
   .dropdown-title

packages/@vuepress/theme-default/components/Home.vue

@@ -71,8 +71,6 @@ export default {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .home
   padding $navbarHeight 2rem 0
   max-width 960px

packages/@vuepress/theme-default/components/NavLinks.vue

@@ -116,8 +116,6 @@ export default {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .nav-links
   display inline-block
   a

packages/@vuepress/theme-default/components/Navbar.vue

@@ -86,8 +86,6 @@ function css (el, property) {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 $navbar-vertical-padding = 0.7rem
 $navbar-horizontal-padding = 1.5rem
 

packages/@vuepress/theme-default/components/Page.vue

@@ -195,7 +195,6 @@ function find (page, items, offset) {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
 @require '../styles/wrapper.styl'
 
 .page

packages/@vuepress/theme-default/components/Sidebar.vue

@@ -79,8 +79,6 @@ function resolveOpenGroupIndex (route, items) {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .sidebar
   ul
     padding 0

packages/@vuepress/theme-default/components/SidebarButton.vue

@@ -7,8 +7,6 @@
 </template>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .sidebar-button
   display none
   width 1.25rem

packages/@vuepress/theme-default/components/SidebarLink.vue

@@ -59,8 +59,6 @@ function renderChildren (h, children, path, route, maxDepth, depth = 1) {
 </script>
 
 <style lang="stylus">
-@import '~@app/style/config'
-
 .sidebar .sidebar-sub-headers
   padding-left 1rem
   font-size 0.95em

packages/@vuepress/theme-default/styles/code.styl

@@ -1,5 +1,3 @@
-@import '~@app/style/config'
-
 .content
   code
     color lighten($textColor, 20%)

packages/@vuepress/theme-default/styles/theme.styl

@@ -1,4 +1,3 @@
-@require '~@app/style/config'
 @require './nprogress'
 @require './code'
 @require './custom-blocks'

packages/docs/docs/config/README.md

@@ -118,6 +118,57 @@ Specify locales for i18n support. For more details, see the guide on [Internatio
 
 A function to control what files should have `<link rel="preload">` resource hints generated. See [shouldPrefetch](https://ssr.vuejs.org/api/#shouldprefetch).
 
+## Styling
+
+### palette
+
+- Type: `Object|String`
+- Default: `undefined`
+
+Set globally available stylus color variables.
+
+If it is string, it needs to be a **absolute path** pointing to a stylus file that defines the color constant:
+
+```js
+module.exports = {
+  palette: path.resolve(__dirname, 'palette.styl'),
+}
+```
+
+::: tip
+When `config.palette` is empty, vuepress will detect whether `.vuepress/palette.styl` exists. If it exists, the file will be used as palette.
+:::
+
+If it is an object, it needs to be an object with key as the color name and value as the HEX color value.
+
+```js
+module.exports = {
+  palette: {
+    // Internal default color constants can be 
+    // modified to quickly modify global styles.
+    $accentColor: '#3eaf7c',
+    $textColor: '#2c3e50',
+    $borderColor: '#eaecef',
+    $codeBgColor: '#282c34',
+    $arrowBgColor: '#ccc',
+
+    // Your extra colors
+    $shadowColor: '#ddd'
+  }
+}
+```
+
+::: tip
+It is worth noting that `modifying global style` via `palette` depends on the strict use of the default palette for your theme (e.g. the `@vuepress/theme-default` you see now). 
+:::
+
+### style
+
+- Type: `string`
+- Default: `undefined`
+
+TODO
+
 ## Theming
 
 ### theme
@@ -138,6 +189,19 @@ Provide config options to the used theme. The options will vary depending on the
 
 - [Default Theme Configuration](../default-theme-config/README.md).
 
+## Pluggable
+
+### plugins
+
+- Type: `Object|Array`
+- Default: `undefined`
+
+For default usage, please refer to [plugin API](../plugin/README.md).
+
+::: tip
+There is a hidden feature. `.vuepress/config.js` also supports all [options](../plugin/README.md#options) plugin API.
+:::
+
 ## Markdown
 
 ### markdown.lineNumbers

packages/docs/docs/default-theme-config/README.md

@@ -459,7 +459,7 @@ You should ONLY write color variables in this file. since `palette.styl` will be
 VuePress provides a convenient way to add extra styles. you can create an `.vuepress/style.styl` file for that:
 
 ```stylus
-content {
+.content {
   font-size 30px
 }
 ```