vuepress-plugin-autobar-improvement

vuepress-plugin-autobar

VuePress sidebar and navbar generator based on file and directory structure. Focus your documents, not sidebar or navbar.

1. Synopsis

Install

 # npm install -D vuepress-plugin-autobar # Waitting author accepted the PR.
 npm install -D boboidream/vuepress-bar

Usage

Add vuepress-plugin-autobar in your site or theme config file. See official docs on using a plugin

// .vuepress/config.js
// or
// .vuepress/theme/index.js

module.exports = {
  plugins: ['autobar']
}

2. Features

• Creates navbar & sidebar: Add navbar prefix to your directories such as nav.guide or nav.01.guide
• Custom sort: Prefix directories with numbers, or add order meta to files such as 01.guide
• Multiple Sidebars
• No configuration
• Adds README.md to the first available group like VuePress web site. (May be disabled by options)
• Possible to pass parameters in directory names. (See advanced example below.)

3. Examples

With Navbar

|- docs/
  |- .vuepress
  |- nav.01.guide/
    |- README.md
  |- nav.02.api/
    |- classes/
      |- member.md

{
  nav: [
    { text: 'Guide', link: '/nav.01.guide/' },
    { text: 'Api', link: '/nav.02.api/' }
  ],
  sidebar: {
    '/nav.01.guide/': [ '' ],
    '/nav.02.api/': [ { title: 'Classes', children: [ '', 'classes/member' ] } ]
  }
}

• Readme is moved into first group: '/nav.02.api/': [ { title: 'Classes', children: [ '', 'classes/member' ] } ] instead of '/nav.02.api/': [ '', { title: 'Classes', children: [ 'classes/member' ] } ]

Without Navbar

|- docs/
  |- .vuepress
  |- 01.guide/
    |- README.md
  |- 02.api/
    |- classes/
      |- member.md

{
  nav: [],
  sidebar: [
    { title: "Guide", children: ["01.guide/"] },
    {
      title: "Api",
      children: [{ title: "Classes", children: ["02.api/classes/member"] }]
    }
  ]
};

4. Advanced

Conventions

It is possible to pass sidebar parameters in directory names. You may pass following parameters after double dash -- separated by comma:

• nc sets collapsable to false.
• dX sets sidebarDepth to X.

|- docs/
  |- 01.guide--nc,d2/
    |- README.md

{
  nav: [],
  sidebar: [
    {
      title: "Guide",
      collapsable: false,
      sidebarDepth: 1,
      children: ["01.guide--nc,d2/"]
    },
  ]
};

Notes

• VuePress requires README.md as default file in a navbar link. Forgetting README.md would skip that creation of that navbar item.

Advanced Options

// .vuepress/config.js
// or
// .vuepress/theme/index.js
const autobar_options = {
  rootDir: 'xxx',
  stripNumbers = true,
  maxLevel = 2,
  navPrefix = "nav",
  skipEmptySidebar = true,
  skipEmptyNavbar = true,
  multipleSideBar = true,
  setHomepage = 'hide' | 'toGroup' | 'top'
};

module.exports = {
  plugins: [
    [ 'autobar', autobar_options ]
  ]
}

tips If you want to use simple links, maybe you will like vuepress-plugin-rpurl.

API

Param	Type	Default	Description
rootDir	String	${ctx.sourceDir}	Root directory where the documents are located.
stripNumbers	Boolean	true	Remove number prefixes from directory names where it helps sorting.
maxLevel	Number	2	Maximum level of recursion for subdirectory traversing.
navPrefix	String	nav	Prefix for directories for navbar and mulitple sidebars.
skipEmptySidebar	Boolean	true	Do not add item to sidebar if directory is empty.
skipEmptyNavbar	Boolean	true	Do not add item to navbar if directory is empty.
multipleSideBar	Boolean	true	Creates multiple sidebars if there are navbar items.
setHomepage	String	hide	hide: Hide homepage link in sidebar. toGroup: Adds README.md into first group of sidebar. top: Show homepage link at top of sidebar
pinyinNav	Boolean	false	Do not translate chinese nav to pinyin.

Tips: pinyinNav: true,Should use with vuepress-plugin-permalink-pinyin.