vuepress-bar

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.