https://github.com/ozum/vuepress-bar
VuePress sidebar and navbar generator based on file and directory structure. Focus your documents, not sidebar or navbar.
https://github.com/ozum/vuepress-bar
Last synced: about 1 month ago
JSON representation
VuePress sidebar and navbar generator based on file and directory structure. Focus your documents, not sidebar or navbar.
- Host: GitHub
- URL: https://github.com/ozum/vuepress-bar
- Owner: ozum
- Created: 2019-06-20T14:36:29.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-11-08T18:07:51.000Z (over 1 year ago)
- Last Synced: 2025-03-31T08:11:16.721Z (about 2 months ago)
- Language: JavaScript
- Size: 521 KB
- Stars: 90
- Watchers: 2
- Forks: 40
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# vuepress-bar
VuePress sidebar and navbar generator based on file and directory structure. Focus your documents, not sidebar or navbar.
# Synopsis
```js
//.vuepress/config.js
const getConfig = require("vuepress-bar");
const { nav, sidebar } = getConfig();
module.exports = { themeConfig: { nav, sidebar } };
```
# Usage
## 1. Get Menu & Bar Configuration
```js
// .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
```js
// .vuepress/config.js
module.exports = { themeConfig: { nav, sidebar } };
```
### Alternative 2: Modification
```js
// .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
```
```js
{
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
```
```js
{
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
```
```js
{
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"**
```ts
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**
```ts
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.
```ts
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. |