Overview

The plugin provides the following options and lists the default values:

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {
      sort: {
        mode: "asc",
        readmeFirst: true,
      },
      title: {
        mode: "titlecase",
        map: {}
      },
      sidebarDepth: 1,
      collapse: {
        open: false,
        collapseList: [],
        uncollapseList: []
      },
      ignore: [],
      git: {
        trackStatus: 'all'
      }
    }
  }
}

sort

1. built-in rules

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {
      sort: {
        // more options: 
        // `asc`、`desc`、`created_time_asc`、`created_time_desc`
        mode: "asc"
      }
    }
  }
}

Before using the created_time_asc、created_time_desc options，you should use git (opens new window) to track your file.

2. custom rules

When the built-in rules do not meet your needs, you can use the custom mode:

// example: sort according to the last character of the filename
// the filename are `filez-1`、`filed-3` and `filea-1`

const sortFn = (a, b) => {
  const lastA = a.filename.split("-")[1]
  const lastB = b.filename.split("-")[1]
  
  return lastA > lastB ? 1 : -1
}

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {
      sort: {
        mode: 'custom',
        fn: sortFn
      },
    }
  },
}

If you want to sort according to other attributes of the file,you can visit vuepress-types (opens new window).

3. precise sort

Above the sort rules, you also want some-filename sort before or after other-filename，you can use the autoPrev/autoNext in the markdown file.

4. value sort（v2.3.0）

More friendly than built-in rules and simpler than precise sort, you can use autoSort in the markdown file.

title

We always use kebabcase for the filename, but titlecase is more friendly to display on the page.

1. built-in mode

module.exports = {
 plugins: {
    "vuepress-plugin-auto-sidebar": {
      title: {
        // more options: 
        // `default`、`lowercase`、`uppercase`、`capitalize`、`camelcase`、`kebabcase`、`titlecase`
        mode: "titlecase"
      }
    }
  }
}

If your docs folder as follows:

docs
├── exampleMenu1
│   ├── exampleSubMenu1-a
│   │   └── file1.md
│   ├── exampleSubMenu1-b
│   │   └── file1.md
│   └── exampleSubMenu1-c
│       ├── file1.md
│       ├── file2.md
│       └── file3.md
├── exampleMenu2
│   ├── file1.md
│   └── README.md

And you choose the titlecase,you will get:

exampleSubMenu1-a => Example Sub Menu1 A
exampleSubMenu1-b => Example Sub Menu1 B
exampleSubMenu1-c => Example Sub Menu1 C
exampleMenu2 => Example Menu2

2. path map

On the basis of titlecase mode, use the map:

module.exports = {
  plugins: [
    "vuepress-plugin-auto-sidebar": {
      title: {
        mode: "titlecase",
        map: {
          "/exampleMenu1/exampleSubMenu1-a/": "🎉 Hello Vuepress 🎉",
          "/exampleMenu1/exampleSubMenu1-c/": "🎉 Auto Sidebar 🎉"
        }
      }
    }
  ],
}

And you will get:

exampleSubMenu1-a => 🎉 Hello Vuepress 🎉
exampleSubMenu1-b => Example Sub Menu1 B
exampleSubMenu1-c => 🎉 Auto Sidebar 🎉
exampleMenu2 => Example Menu2

sidebarDepth

The default depth is 1, which extracts the h2 headers. Setting it to 0 disables the header links, and the max value is 2 which extracts both h2 and h3 headers.

module.exports = {
  plugins: [
    "vuepress-plugin-auto-sidebar": {
      sidebarDepth: 1,
    }
  ]
}

If you want override for the specified markdown file, you can also use the sidebarDepth.

collapse

When you have a lot of markdown files, the sidebar will also become bloated, collapse may help you to solve the problem.

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {
      collapse: {
        open: true
      }
    }
  },
}

But more often, only some folders will have many files, so you can just fold this part.

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {
      collapse: {
        collapseList: [
          "/demo/large-files/"
        ]
      }
    }
  }
}

The usage scenario of uncollapseList is the opposite.

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {
      collapse: {
        open: true,
        uncollapseList: [
          "/demo/few-files/"
        ]
      }
    }
  },
}

ignore

If you do not want part of markdown files display on the sidebar:

module.exports = {
  plugins: [
    "vuepress-plugin-auto-sidebar": {
      ignore: [
        // example:
        // ignore files starting with `ignore-` in the `/menu3/menu 3-3/` directory
        {
          menu: "/menu3/menu3-3/",
          regex: "ignore-*"
        }
      ]
    }
  ]
}

If you just ignore some file, you can use the autoIgnore in the markdown file.

removeEmptyGroup

When you configure all files in a folder with autoGroup, it will cause the default group to be empty, and when you want to hide it you can use:

module.exports = {
  plugins: [
    "vuepress-plugin-auto-sidebar": {
      removeEmptyGroup: true
    }
  ]
}

nav

This plugin also provides a way to generate nav.

1. add the script to the package.json

   {
     "scripts": {
       "docs:nav": "vuepress nav docs"
     }
   }
   

2. execute command

   npm run docs:nav
   

   It will create a nav.js in your .vuepress folder.

3. require nav file

   const nav = require("./nav.js");
   
   module.exports = {
     plugins: {
       "vuepress-plugin-auto-sidebar": {}
     },
     themeConfig: {
       nav
     }
   }
   

git

Support from 2.4.0-alpha.4 onwards

VuePress v2 no longer supports dynamic modification of sidebar, you need to configure it manually, but some content is just a draft, do not want to submit directly to Github.
So here's a compromise:

const sidebarConf = require('./sidebar')

module.exports = {
  plugins: [
    ["vuepress-plugin-auto-sidebar", {
      git: {
        // `add` means that files with `git add` are tracked
        // `commit` means that files with `git commit` are tracked
        trackStatus: 'add' // or 'commit'
      }
    }]
  ],
  themeConfig: {
    sidebar: sidebarConf
  }
}