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.

ozum/vuepress-bar