feat: refine group

- isolate a group's open status with `isolated: true`
- config a isolated group's initial open status with `initialIsolatedOpen: true`
- config a group's sidebarDepth with `sidebarDepth: 2`
- nested sidebar groups

Author: zyy7259

docs/default-theme-config/README.md

@@ -199,6 +199,12 @@ module.exports = {
 
 Sidebar groups are collapsable by default. You can force a group to be always open with `collapsable: false`.
 
+When a group is open, other groups at the same level will be automatically closed. You can isolate a group's open status with `isolated: true`. And then you can config its initial open status with `initialIsolatedOpen: true`.
+
+You can config a group's sidebarDepth with `sidebarDepth: 2`.
+
+You can nest sidebar groups.
+
 ### Multiple Sidebars
 
 If you wish to display different sidebars for different sections of content, first organize your pages into directories for each desired section:
@@ -333,7 +339,7 @@ module.exports = {
 ```
 
 ::: warning Note
-Unlike the [built-in search](#built-in-search) engine which works out of the box, [Algolia DocSearch](https://community.algolia.com/docsearch/) requires you to submit your site to them for indexing before it starts working. 
+Unlike the [built-in search](#built-in-search) engine which works out of the box, [Algolia DocSearch](https://community.algolia.com/docsearch/) requires you to submit your site to them for indexing before it starts working.
 :::
 
 For more options, refer to [Algolia DocSearch's documentation](https://github.com/algolia/docsearch#docsearch-options).

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

@@ -164,7 +164,7 @@ module.exports = {
 }
 ```
 
-::: tip 
+::: tip
 值得一提的是，当你禁用此选项时，此功能的相应脚本将不会被加载，这是我们性能优化的一个小点。
 :::
 
@@ -196,6 +196,12 @@ module.exports = {
 
 侧边栏的每个子组默认是可折叠的，你可以设置 `collapsable: false` 来让一个组永远都是展开状态。
 
+当一个子组被展开时，跟它同级的其他子组会被折叠。你可以设置 `isolated: true` 来隔离一个组的展开状态。然后你可以设置 `initialIsolatedOpen: true` 来让一个被隔离的组在一开始就处于展开状态。
+
+你可以通过 `sidebarDepth: 2` 来设置一个组的 sidebarDepth。
+
+你可以嵌套组。
+
 ### 多个侧边栏
 
 如果你想为不同的页面组来显示不同的侧边栏，首先，将你的页面文件组织成下述的目录结构：

lib/default-theme/Page.vue

@@ -142,7 +142,7 @@ function find (page, items, offset) {
   const res = []
   items.forEach(item => {
     if (item.type === 'group') {
-      res.push(...item.children || [])
+      res.push(...(item.descendants || item.children))
     } else {
       res.push(item)
     }

lib/default-theme/Sidebar.vue

@@ -7,9 +7,7 @@
         <SidebarGroup v-if="item.type === 'group'"
           :item="item"
           :first="i === 0"
-          :open="i === openGroupIndex"
-          :collapsable="item.collapsable"
-          @toggle="toggleGroup(i)"/>
+          :collapsable="item.collapsable"/>
         <SidebarLink v-else :item="item"/>
       </li>
     </ul>
@@ -21,51 +19,10 @@
 import SidebarGroup from './SidebarGroup.vue'
 import SidebarLink from './SidebarLink.vue'
 import NavLinks from './NavLinks.vue'
-import { isActive } from './util'
 
 export default {
   components: { SidebarGroup, SidebarLink, NavLinks },
-  props: ['items'],
-  data () {
-    return {
-      openGroupIndex: 0
-    }
-  },
-  created () {
-    this.refreshIndex()
-  },
-  watch: {
-    '$route' () {
-      this.refreshIndex()
-    }
-  },
-  methods: {
-    refreshIndex () {
-      const index = resolveOpenGroupIndex(
-        this.$route,
-        this.items
-      )
-      if (index > -1) {
-        this.openGroupIndex = index
-      }
-    },
-    toggleGroup (index) {
-      this.openGroupIndex = index === this.openGroupIndex ? -1 : index
-    },
-    isActive (page) {
-      return isActive(this.$route, page.path)
-    }
-  }
-}
-
-function resolveOpenGroupIndex (route, items) {
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i]
-    if (item.type === 'group' && item.children.some(c => isActive(route, c.path))) {
-      return i
-    }
-  }
-  return -1
+  props: ['items']
 }
 </script>
 

lib/default-theme/SidebarGroup.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="sidebar-group" :class="{ first, collapsable }">
-    <p class="sidebar-heading" :class="{ open }" @click="$emit('toggle')">
+    <p class="sidebar-heading" :class="{ open }" @click="handleClickToggle">
       <span>{{ item.title }}</span>
       <span class="arrow"
         v-if="collapsable"
@@ -9,21 +9,77 @@
     <DropdownTransition>
       <ul class="sidebar-group-items" ref="items" v-if="open || !collapsable">
         <li v-for="child in item.children">
-          <SidebarLink :item="child"/>
+          <SidebarGroup v-if="child.type === 'group'"
+            :item="child"
+            :collapsable="child.collapsable"/>
+          <SidebarLink v-else :item="child" :sidebarDepth="item.sidebarDepth"/>
         </li>
       </ul>
     </DropdownTransition>
   </div>
 </template>
 
 <script>
+import Vue from 'vue'
 import SidebarLink from './SidebarLink.vue'
 import DropdownTransition from './DropdownTransition.vue'
+import { isActive } from './util'
+
+const hub = new Vue()
 
 export default {
   name: 'SidebarGroup',
-  props: ['item', 'first', 'open', 'collapsable'],
-  components: { SidebarLink, DropdownTransition }
+  components: { SidebarLink, DropdownTransition },
+  props: [
+    'item',
+    'first',
+    'collapsable'
+  ],
+  data () {
+    return {
+      open: this.item.isolated && this.item.initialIsolatedOpen || false
+    }
+  },
+  created () {
+    this.initToggleEvent()
+    this.refreshOpen()
+  },
+  watch: {
+    '$route' () {
+      this.refreshOpen()
+    }
+  },
+  methods: {
+    initToggleEvent () {
+      const onToggle = this.onToggle.bind(this)
+      hub.$on('toggle', onToggle)
+      this.$on('hook:destroyed', () => {
+        hub.$off('toggle', onToggle)
+      })
+    },
+    refreshOpen () {
+      const arr = this.item.descendants || this.item.children
+      if (arr.some(c => isActive(this.$route, c.path))) {
+        this.open = true
+      }
+    },
+    handleClickToggle () {
+      this.open = !this.open
+      if (this.open && !this.item.isolated) {
+        hub.$emit('toggle', { depth: this.item.depth, target: this })
+      }
+    },
+    onToggle ({ depth, target }) {
+      if (
+        target.$parent === this.$parent &&
+        depth === this.item.depth &&
+        !this.item.isolated &&
+        target !== this
+      ) {
+        this.open = false
+      }
+    }
+  }
 }
 </script>
 
@@ -34,7 +90,7 @@ export default {
   .sidebar-group
     padding-left 0.5em
   &:not(.collapsable)
-    .sidebar-heading
+    > .sidebar-heading
       cursor auto
       color inherit
 

lib/default-theme/SidebarLink.vue

@@ -3,8 +3,14 @@ import { isActive, hashRE, groupHeaders } from './util'
 
 export default {
   functional: true,
-  props: ['item'],
-  render (h, { parent: { $page, $site, $route }, props: { item }}) {
+  props: ['item', 'sidebarDepth'],
+  render (
+    h,
+    {
+      parent: { $page, $site, $route },
+      props: { item, sidebarDepth: groupSidebarDepth }
+    }
+  ) {
     // use custom active class matching logic
     // due to edge case of paths ending with / + hash
     const selfActive = isActive($route, item.path)
@@ -14,10 +20,17 @@ export default {
       ? selfActive || item.children.some(c => isActive($route, item.basePath + '#' + c.slug))
       : selfActive
     const link = renderLink(h, item.path, item.title || item.path, active)
-    const configDepth = $page.frontmatter.sidebarDepth != null
-      ? $page.frontmatter.sidebarDepth
-      : $site.themeConfig.sidebarDepth
+
+    let configDepth
+    if ($page.frontmatter.sidebarDepth != null) {
+      configDepth = $page.frontmatter.sidebarDepth
+    } else if (groupSidebarDepth != null) {
+      configDepth = groupSidebarDepth
+    } else {
+      $site.themeConfig.sidebarDepth
+    }
     const maxDepth = configDepth == null ? 1 : configDepth
+
     const displayAllHeaders = !!$site.themeConfig.displayAllHeaders
     if (item.type === 'auto') {
       return [link, renderChildren(h, item.children, item.basePath, $route, maxDepth)]

lib/default-theme/util.js

@@ -191,26 +191,31 @@ function ensureEndingSlash (path) {
     : path + '/'
 }
 
-function resolveItem (item, pages, base, isNested) {
+function resolveItem (item, pages, base, depth = 0) {
   if (typeof item === 'string') {
     return resolvePage(pages, item, base)
   } else if (Array.isArray(item)) {
     return Object.assign(resolvePage(pages, item[0], base), {
       title: item[1]
     })
   } else {
-    if (isNested) {
-      console.error(
-        '[vuepress] Nested sidebar groups are not supported. ' +
-        'Consider using navbar + categories instead.'
-      )
-    }
-    const children = item.children || []
+    depth++
+    const descendants = item.descendants || []
+    const children = (item.children || []).map(child => {
+      const resolvedItem = resolveItem(child, pages, base, depth)
+      ;[].push.apply(descendants, resolvedItem.descendants || [resolvedItem])
+      return resolvedItem
+    })
     return {
       type: 'group',
       title: item.title,
-      children: children.map(child => resolveItem(child, pages, base, true)),
-      collapsable: item.collapsable !== false
+      children,
+      descendants,
+      collapsable: item.collapsable !== false,
+      isolated: item.isolated === true,
+      initialIsolatedOpen: item.initialIsolatedOpen === true,
+      sidebarDepth: item.sidebarDepth,
+      depth
     }
   }
 }