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 boboidream/vuepress-bar

  npm install -D vuepress-plugin-autobar

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.

注意！！！

2019年的文章，害人不浅，现在是2022年，我照着做居然报中文不能找到对应的html, 以为是bar 的问题，查看源码，作者在2020年试着去翻译sidebar里的中文，放弃了， 后面查看了pinyin的包，四个版本1.1.0,1.0.0,0.2.0,0.1.0 看了就是0.2.0是19年的，退到这个版本就好了，

当然还有个坑，就是作者不发npm包，github中国是不友好的，我做活雷锋了 按原作者的安装方法， 在pageage.json文件中是这样显示

...
"vuepress-plugin-autobar": "github:boboidream/vuepress-bar"
...

这种会在npm install会报错

使用 vuepress-plugin-permalink-pinyin 此插件 请锁死 0.2.0 这个版本