0.4.4 • Published 4 months ago

vuepress-bar v0.4.4

Weekly downloads
283
License
MIT
Repository
github
Last release
4 months ago

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

ParamTypeDefaultDescription
stripNumbersBooleantrueRemove number prefixes from directory names where it helps sorting.
maxLevelNumber2Maximum level of recursion for subdirectory traversing.
navPrefixStringnavPrefix for directories for navbar and mulitple sidebars.
skipEmptySidebarBooleantrueDo not add item to sidebar if directory is empty.
skipEmptyNavbarBooleantrueDo not add item to navbar if directory is empty.
multipleSideBarBooleantrueCreate multiple sidebars if there are navbar items.
addReadMeToFirstGroupBooleantrueAdd README.md into first group of sidebar. (vuepress website's behaviour)
mixDirectoriesAndFilesAlphabeticallyBooleantrueAdd directories to alphabetic positions between files. (i.e. 01-file, 02-folder, 03-file )
pinyinNavBooleanfalseTranslate chinese nav to pinyin.
filterFunctionFİlter function to filter files. Front Matter meta data is passed as an object.
0.4.4

4 months ago

0.4.3

4 months ago

0.4.1

8 months ago

0.4.0

8 months ago

0.4.2

8 months ago

0.3.6

11 months ago

0.3.5

12 months ago

0.3.4

12 months ago

0.3.3

12 months ago

0.3.2

1 year ago

0.3.1

2 years ago

0.3.0

2 years ago

0.2.7

2 years ago

0.2.6

2 years ago

0.2.5

2 years ago

0.2.4

2 years ago

0.2.3

2 years ago

0.2.2

2 years ago

0.2.1

2 years ago

0.2.0

2 years ago

0.1.1

3 years ago

0.1.0

3 years ago

0.0.4

3 years ago

0.0.3

3 years ago

0.0.2

3 years ago

0.0.1

3 years ago