wip: sidebar order and nesting

Author: yyx990803

README.md

@@ -3,3 +3,15 @@
 # VuePress
 
 > Minimalistic docs generator with Vue component based layout system
+
+## Why
+
+- **Writing First**: minimal setup, all you need is a markdown file.
+
+- **Vue-powered**: Use custom Vue components inside markdown, and develop custom themes using Vue single file components.
+
+- **Great Dev Experience**: enjoy the same enjoyable development experience of a Vue app. Leverage the full power of webpack (hot-reload, pre-processors), generate SEO-friendly static HTML, and works as an SPA after initial page load.
+
+- **Optimized for Docs**: many [built-in markdown extensions](./markdown.md) and default theme features for writing great documentation.
+
+- **GitHub Friendly**: source markdown files can link to each other using relative links that ends in `.md` so they are also readable on GitHub, auto-generates page edit links if a repo is provided.

docs/.vuepress/config.js

@@ -9,15 +9,40 @@ module.exports = {
     ['link', { rel: 'icon', href: `${base}logo.png` }]
   ],
   themeConfig: {
+    // sidebar config
     sidebar: [
-      '/',
+      '/getting-started',
       '/markdown',
       '/assets',
       '/using-vue',
       '/config',
       '/default-theme',
       '/theming',
-      '/deploy'
-    ]
+      '/deploy',
+      // nesting
+      ['Nesting', [
+        '/markdown',
+        '/assets'
+      ]]
+    ],
+
+    // multi-category sidebar config
+
+    // sidebar: {
+    //   '*': [/* ... */],
+    //   '/guide/': [/* ... */],
+    //   '/tutorial/': [/* ... */],
+    //   '/api/': [/* ... */]
+    // },
+
+    // navbar config
+
+    // nav: [
+    //   {
+    //     title: 'Guide',
+    //     link: '/getting-started',
+    //   },
+    //   // ...
+    // ]
   }
 }

docs/README.md

@@ -1,7 +1,3 @@
----
-navTitle: Getting Started
----
-
 # VuePress
 
 > Minimalistic docs generator with Vue component based layout system
@@ -17,59 +13,3 @@ navTitle: Getting Started
 - **Optimized for Docs**: many [built-in markdown extensions](./markdown.md) and default theme features for writing great documentation.
 
 - **GitHub Friendly**: source markdown files can link to each other using relative links that ends in `.md` so they are also readable on GitHub, auto-generates page edit links if a repo is provided.
-
-## Quickstart
-
-``` bash
-# install globally
-npm install -g vuepress
-
-# create a markdown file
-echo "# Hello VuePress!" > index.md
-
-# start writing
-vuepress dev .
-
-# build
-vuepress build .
-```
-
-## Inside an Existing Project
-
-``` bash
-# install as a dependency
-npm install -D vuepress
-
-# create a docs directory
-mkdir docs
-# create a markdown file
-echo "# Hello VuePress!" > docs/index.md
-
-# start writing
-npx vuepress dev docs
-```
-
-Or, add some scripts to `package.json`:
-
-``` json
-{
-  "scripts": {
-    "docs:dev": "vuepress dev docs",
-    "docs:build": "vuepress build docs"
-  }
-}
-```
-
-Then you can start writing with:
-
-``` bash
-npm run docs:dev
-```
-
-To generate static assets, run:
-
-``` bash
-npm run docs:build
-```
-
-By default the built files will be in `.vuepress/dist`. The files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services.

docs/getting-started.md

@@ -0,0 +1,57 @@
+# Getting Started
+
+## Quickstart
+
+``` bash
+# install globally
+npm install -g vuepress
+
+# create a markdown file
+echo "# Hello VuePress!" > index.md
+
+# start writing
+vuepress dev .
+
+# build
+vuepress build .
+```
+
+## Inside an Existing Project
+
+``` bash
+# install as a dependency
+npm install -D vuepress
+
+# create a docs directory
+mkdir docs
+# create a markdown file
+echo "# Hello VuePress!" > docs/index.md
+
+# start writing
+npx vuepress dev docs
+```
+
+Or, add some scripts to `package.json`:
+
+``` json
+{
+  "scripts": {
+    "docs:dev": "vuepress dev docs",
+    "docs:build": "vuepress build docs"
+  }
+}
+```
+
+Then you can start writing with:
+
+``` bash
+npm run docs:dev
+```
+
+To generate static assets, run:
+
+``` bash
+npm run docs:build
+```
+
+By default the built files will be in `.vuepress/dist`. The files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services.

lib/default-theme/Layout.vue

@@ -2,10 +2,20 @@
   <div class="theme-container">
     <div class="sidebar">
       <ul>
-        <li v-for="page in sortedPages">
-          <router-link :to="page.path">
-            {{ page.frontmatter.navTitle || page.title || page.path }}
+        <li v-for="item in sidebarItems">
+          <router-link v-if="item.type === 'page'" :to="item.path">
+            {{ item.title || item.path }}
           </router-link>
+          <div class="sidebar-group" v-else-if="item.type === 'heading'">
+            <p class="sidebar-heading">{{ item.title }}</p>
+            <ul>
+              <li v-for="child in item.children">
+                <router-link v-if="child.type === 'page'" :to="child.path">
+                  {{ child.title || child.path }}
+                </router-link>
+              </li>
+            </ul>
+          </div>
         </li>
       </ul>
     </div>
@@ -18,36 +28,16 @@
 import nprogress from 'nprogress'
 import Index from './Index.vue'
 import Page from './Page.vue'
-
-function normalize (path) {
-  return path.replace(/\.(md|html)$/, '')
-}
-
-function findIndex (order, page) {
-  const pagePath = normalize(page.path)
-  for (let i = 0; i < order.length; i++) {
-    if (normalize(order[i]) === pagePath) {
-      return i
-    }
-  }
-  return Infinity
-}
+import resolveSidebar from './resolveSidebar'
 
 export default {
   components: { Index, Page },
   computed: {
-    sortedPages () {
-      const pages = this.$site.pages
-      const order = this.$site.themeConfig.sidebar
-      if (!order) {
-        return pages
-      } else {
-        return pages.slice().sort((a, b) => {
-          const aIndex = findIndex(order, a)
-          const bIndex = findIndex(order, b)
-          return aIndex - bIndex
-        })
-      }
+    sidebarItems () {
+      return resolveSidebar(
+        this.$route,
+        this.$site
+      )
     }
   },
   mounted () {

lib/default-theme/resolveSidebar.js

@@ -0,0 +1,53 @@
+export default function resolveSidebar (route, site) {
+  const { pages, themeConfig } = site
+  const sidebarConfig = themeConfig.sidebar
+  if (!sidebarConfig) {
+    return pages
+  } else {
+    const matchingConfig = Array.isArray(sidebarConfig)
+      ? sidebarConfig
+      : resolveMatchingSidebar(route, sidebarConfig)
+    return matchingConfig.map(item => resolveItem(item, site.pages))
+  }
+}
+
+function resolveMatchingSidebar (route, sidebarConfig) {
+  for (const base in sidebarConfig) {
+    if (ensureEndingSlash(route.path).indexOf(base) === 0) {
+      return sidebarConfig[base]
+    }
+  }
+}
+
+function ensureEndingSlash (path) {
+  return /(\.html|\/)$/.test(path)
+    ? path
+    : path + '/'
+}
+
+function resolveItem (item, pages) {
+  if (typeof item === 'string') {
+    return Object.assign({ type: 'page' }, findPage(pages, item))
+  } else if (Array.isArray(item)) {
+    return {
+      type: 'heading',
+      title: item[0],
+      children: (item[1] || []).map(child => resolveItem(child, pages))
+    }
+  } else {
+    throw new Error(`Invalid sidebar item config: ${item}`)
+  }
+}
+
+function findPage (pages, path) {
+  path = normalize(path)
+  for (let i = 0; i < pages.length; i++) {
+    if (normalize(pages[i].path) === path) {
+      return pages[i]
+    }
+  }
+}
+
+function normalize (path) {
+  return path.replace(/\.(md|html)$/, '')
+}

lib/default-theme/theme.stylus

@@ -31,13 +31,13 @@ body
     padding-left 1.25em
     &:hover
       color darken(#41b883, 5%)
-    &.router-link-exact-active
+    &.router-link-active
       font-weight 600
       color darken(#41b883, 5%)
       border-left-color darken(#41b883, 5%)
 
 .markdown
-  max-width 720px
+  max-width 760px
   margin 2em auto
   padding 0 2em
 
@@ -151,7 +151,7 @@ p
     border 1px solid #ddd
     border-radius 4px
 
-@media (max-width: 879px)
+@media (max-width: 959px)
   body
     font-size 15px
   .sidebar
@@ -163,7 +163,7 @@ p
     margin 1.5em 0
     padding 0 1.5em
 
-@media (max-width: 639px)
+@media (max-width: 719px)
   body
     font-size 15px
   .sidebar