vuepress-bar

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

Synopsis

//.vuepress/config.js
const getConfig = require("vuepress-bar");

const { nav, sidebar } = getConfig();

module.exports = { themeConfig: { nav, sidebar } };

Usage

1. Get Menu & Bar Configuration

// .vuepress/config.js
const { nav, sidebar } = getConfig(options); // Use default location of `.vuepress`: `${__dirname}/..`
const { nav, sidebar } = getConfig("path/to/.vuepress/..", options); // Point to *parent* dir of `.vuepress`.

2. Merge with VuePress Configuration

Alternative 1: No Modification

// .vuepress/config.js
module.exports = { themeConfig: { nav, sidebar } };

Alternative 2: Modification

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [{ text: 'pg-structure', link: 'https://www.pg-structure.com/' }, ...nav]
    sidebar,
  }
};

** See advanced section below for more advanced modifications such as overriding.

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 the VuePress web site. (Maybe disabled by options)
• Pass parameters in directory names. (See advanced example below.)
• Fİlter based on Front Matter meta data.

Examples with Explanations

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"] }]
    }
  ]
};

Advanced

Parameters

It is possible to pass sidebar parameters in directory names. You may pass the following parameters after double dash -- separated by a 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/"]
    },
  ]
};

Overriding

You may want to override generated navbar or sidebar. That is the reason why vuepress-bar isn't written as a plugin. You can override generated config.

Rename "Api" to "API"

const { nav, sidebar } = getConfig();

// Find item with text "Api" and change it to "API".
nav.find((item) => item.text === "Api").text = "API";

Filter Some Entries

module.exports = {
  themeConfig: {
    nav,
    sidebar: sidebar.filter((i) => i.title !== "Node Modules"),
  },
};

Filter Some Entries with Meta Data

Use YAML meta data (Front Matter).

CAUTION if you use "Theme API" and filter pages in the ready function: The filter option has to be the same as what is in the ready function or there will be an error because the ready function deletes the pages.

const { nav, sidebar } = getConfig({ filter: (meta) => meta.draft !== true });

Notes

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

Options

| Param | Type | Default | Description | | ------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------ | | 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 | Create multiple sidebars if there are navbar items. | | addReadMeToFirstGroup | Boolean | true | Add README.md into first group of sidebar. (vuepress website's behaviour) | | mixDirectoriesAndFilesAlphabetically | Boolean | true | Add directories to alphabetic positions between files. (i.e. 01-file, 02-folder, 03-file ) | | pinyinNav | Boolean | false | Translate chinese nav to pinyin. | | filter | Function | | Fİlter function to filter files. Front Matter meta data is passed as an object. |