feat($theme-default): smooth scroll (close #567) (#1881)

* feat($plugin-active-header-links): replace throttle by debounce

* feat($theme-default): use plugin-smooth-scroll (close #567)

* feat($theme-default): smooth-scroll option

* docs: smooth-scroll option of default theme

* docs: enable smooth-scroll

packages/@vuepress/plugin-active-header-links/clientRootMixin.js

@@ -1,6 +1,6 @@
 /* global AHL_SIDEBAR_LINK_SELECTOR, AHL_HEADER_ANCHOR_SELECTOR */
 
-import throttle from 'lodash.throttle'
+import debounce from 'lodash.debounce'
 
 export default {
   mounted () {
@@ -8,7 +8,7 @@ export default {
   },
 
   methods: {
-    onScroll: throttle(function () {
+    onScroll: debounce(function () {
       this.setActiveHash()
     }, 300),
 

packages/@vuepress/plugin-active-header-links/package.json

@@ -18,7 +18,7 @@
     "generator"
   ],
   "dependencies": {
-    "lodash.throttle": "^4.1.1"
+    "lodash.debounce": "^4.0.8"
   },
   "author": "ULIVZ <chl814@foxmail.com>",
   "license": "MIT",

packages/@vuepress/theme-default/index.js

@@ -1,46 +1,54 @@
 const path = require('path')
 
 // Theme API.
-module.exports = (options, ctx) => ({
-  alias () {
-    const { themeConfig, siteConfig } = ctx
-    // resolve algolia
-    const isAlgoliaSearch = (
-      themeConfig.algolia
-      || Object.keys(siteConfig.locales && themeConfig.locales || {})
-        .some(base => themeConfig.locales[base].algolia)
-    )
-    return {
-      '@AlgoliaSearchBox': isAlgoliaSearch
-        ? path.resolve(__dirname, 'components/AlgoliaSearchBox.vue')
-        : path.resolve(__dirname, 'noopModule.js')
-    }
-  },
+module.exports = (options, ctx) => {
+  const { themeConfig, siteConfig } = ctx
 
-  plugins: [
-    ['@vuepress/active-header-links', options.activeHeaderLinks],
-    '@vuepress/search',
-    '@vuepress/plugin-nprogress',
-    ['container', {
-      type: 'tip',
-      defaultTitle: {
-        '/': 'TIP',
-        '/zh/': '提示'
+  // resolve algolia
+  const isAlgoliaSearch = (
+    themeConfig.algolia
+    || Object
+        .keys(siteConfig.locales && themeConfig.locales || {})
+        .some(base => themeConfig.locales[base].algolia)
+  )
+
+  const enableSmoothScroll = themeConfig.smoothScroll === true
+
+  return {
+    alias () {
+      return {
+        '@AlgoliaSearchBox': isAlgoliaSearch
+          ? path.resolve(__dirname, 'components/AlgoliaSearchBox.vue')
+          : path.resolve(__dirname, 'noopModule.js')
       }
-    }],
-    ['container', {
-      type: 'warning',
-      defaultTitle: {
-        '/': 'WARNING',
-        '/zh/': '注意'
-      }
-    }],
-    ['container', {
-      type: 'danger',
-      defaultTitle: {
-        '/': 'WARNING',
-        '/zh/': '警告'
-      }
-    }]
-  ]
-})
+    },
+
+    plugins: [
+      ['@vuepress/active-header-links', options.activeHeaderLinks],
+      '@vuepress/search',
+      '@vuepress/plugin-nprogress',
+      ['container', {
+        type: 'tip',
+        defaultTitle: {
+          '/': 'TIP',
+          '/zh/': '提示'
+        }
+      }],
+      ['container', {
+        type: 'warning',
+        defaultTitle: {
+          '/': 'WARNING',
+          '/zh/': '注意'
+        }
+      }],
+      ['container', {
+        type: 'danger',
+        defaultTitle: {
+          '/': 'WARNING',
+          '/zh/': '警告'
+        }
+      }],
+      ['smooth-scroll', enableSmoothScroll]
+    ]
+  }
+}

packages/@vuepress/theme-default/package.json

@@ -37,6 +37,7 @@
     "lodash": "^4.17.15",
     "stylus": "^0.54.5",
     "stylus-loader": "^3.0.2",
-    "vuepress-plugin-container": "^2.0.0"
+    "vuepress-plugin-container": "^2.0.0",
+    "vuepress-plugin-smooth-scroll": "^0.0.3"
   }
 }

packages/docs/docs/.vuepress/config.js

@@ -35,6 +35,7 @@ module.exports = ctx => ({
       apiKey: '3a539aab83105f01761a137c61004d85',
       indexName: 'vuepress'
     }) : null,
+    smoothScroll: true,
     locales: {
       '/': {
         label: 'English',

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

@@ -442,6 +442,19 @@ next: ./my-next-page # Will overwrite 'nextLinks' property from themeConfig
 ---
 ```
 
+## Smooth Scrolling
+
+The `themeConfig.smoothScroll` option allows you to enable smooth scrolling.
+
+``` js
+// .vuepress/config.js
+module.exports = {
+  themeConfig: {
+    smoothScroll: true
+  }
+}
+```
+
 ## 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`:

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

@@ -419,6 +419,19 @@ editLink: false
 ---
 ```
 
+## 页面滚动
+
+你可以通过 `themeConfig.smoothScroll` 选项来启用页面滚动效果。
+
+``` js
+// .vuepress/config.js
+module.exports = {
+  themeConfig: {
+    smoothScroll: true
+  }
+}
+```
+
 ## 自定义页面类
 
 有时候你可能需要为特定页面添加一个 CSS 类名，以方便针对该页面添加一些专门的 CSS。这种情况下你可以在该页面的 YAML front matter 中声明一个 `pageClass`：

yarn.lock

@@ -7304,10 +7304,6 @@ lodash.templatesettings@^4.0.0:
   dependencies:
     lodash._reinterpolate "~3.0.0"
 
-lodash.throttle@^4.1.1:
-  version "4.1.1"
-  resolved "https://registry.yarnpkg.com/lodash.throttle/-/lodash.throttle-4.1.1.tgz#c23e91b710242ac70c37f1e1cda9274cc39bf2f4"
-
 lodash.unescape@4.0.1:
   version "4.0.1"
   resolved "https://registry.yarnpkg.com/lodash.unescape/-/lodash.unescape-4.0.1.tgz#bf2249886ce514cda112fae9218cdc065211fc9c"
@@ -10465,6 +10461,11 @@ smart-buffer@4.0.2:
   version "4.0.2"
   resolved "https://registry.yarnpkg.com/smart-buffer/-/smart-buffer-4.0.2.tgz#5207858c3815cc69110703c6b94e46c15634395d"
 
+smoothscroll-polyfill@^0.4.3:
+  version "0.4.4"
+  resolved "https://registry.yarnpkg.com/smoothscroll-polyfill/-/smoothscroll-polyfill-0.4.4.tgz#3a259131dc6930e6ca80003e1cb03b603b69abf8"
+  integrity sha512-TK5ZA9U5RqCwMpfoMq/l1mrH0JAR7y7KRvOBx0n2869aLxch+gT9GhN3yUfjiw+d/DiF1mKo14+hd62JyMmoBg==
+
 snapdragon-node@^2.0.1:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/snapdragon-node/-/snapdragon-node-2.1.1.tgz#6c175f86ff14bdb0724563e8f3c1b021a286853b"
@@ -11994,6 +11995,13 @@ vuepress-plugin-flowchart@^1.4.2:
   dependencies:
     flowchart.js "^1.11.3"
 
+vuepress-plugin-smooth-scroll@^0.0.3:
+  version "0.0.3"
+  resolved "https://registry.yarnpkg.com/vuepress-plugin-smooth-scroll/-/vuepress-plugin-smooth-scroll-0.0.3.tgz#6eff2d4c186cca917cc9f7df2b0af7de7c8c6438"
+  integrity sha512-qsQkDftLVFLe8BiviIHaLV0Ea38YLZKKonDGsNQy1IE0wllFpFIEldWD8frWZtDFdx6b/O3KDMgVQ0qp5NjJCg==
+  dependencies:
+    smoothscroll-polyfill "^0.4.3"
+
 w3c-hr-time@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/w3c-hr-time/-/w3c-hr-time-1.0.1.tgz#82ac2bff63d950ea9e3189a58a65625fedf19045"