VitePress Sidebar Configuration Guide
Overview
For various reasons, all sidebars on this site are generated by a sidebar generator developed by the development team. The sidebar plugin provided by VitePress is not used. The following provides a detailed explanation of the sidebar generator configuration.
Structure and Principles
The entry point of the sidebar generator is the index.ts file, located at CrychicDoc/.vitepress/index.ts.
The code structure is as follows:
const dirs = [
"modpack/kubejs"
];import sidebar from "./utils/sidebarGenerator"
import md from "./utils/mdParser"
import Path from "path";
import fs from "fs";
const dirs = [
"modpack/kubejs"
];
export default function sidebars(lang: string): {} {
let ISidebar = {};
dirs.forEach(dir => {
const generator = new sidebar(`docs/${lang}/${dir}`, true);
ISidebar[`${lang}/${dir}/`] = [generator.sidebar]
})
return ISidebar;
}
function logger(string: string, name: string): void {
fs.writeFileSync(Path.join(__dirname, name), `${string}\n`, { flag: 'w+' });
}When you need to add a new directory for automatic scanning, you should add the new path string to this array. The newly added path will be scanned and the corresponding sidebar will be generated and displayed in the corresponding subdomain.
Example
The sidebar generated for modpack/kubejs will appear at https://docs.mihono.cn/<lang>/modpack/kubejs.
Note
The path string should not include the docs/<lang> directory. Before adding a path, make sure it actually exists.
File Scanning
The files in the target directory will be automatically scanned by the generator and the corresponding sidebar will be generated. Each file has the following frontmatter configuration fields.
Tip
This site also supports the native frontmatter style of VitePress. For more details, please refer to here.
| Configuration Field | Purpose | Type | Default |
|---|---|---|---|
title | Sets the title displayed in the sidebar | string | N/A |
noguide | Sets whether the file should be added to the sidebar | boolean | false |
authors | Sets the authors of the file (GitHub usernames), displayed below the page navigation bar | string[] | N/A |
Example
---
title: Example
authors:
- M1hono
- skyraah
---Directory Scanning
In the generator used on this site, directories are not automatically scanned recursively. You need to create an index.md file in the parent directory of the target directory and configure its frontmatter to manually specify which directories should be entered and scanned.
Parsing
The frontmatter in index.md supports additional configuration fields besides the regular file configuration format. It also reads an <Object> object named root, with the following configuration fields and code declaration.
Code Declaration
interface Index {
root: {
title: string,
collapsed?: boolean;
subDir: SubDir[]
}
}interface SubDir {
title: string;
path: string;
noScan?: boolean;
collapsed?: boolean;
file?: string;
}| Configuration Field | Purpose | Type | Default |
|---|---|---|---|
title | Sets the name of the sidebar | string | N/A |
collapsed | Sets whether the sidebar is initially collapsed or expanded, leave empty to disable collapsing | boolean | N/A |
subDir | Sets which subdirectories should be recursively scanned under this directory | SubDir | N/A |
Example
---
root:
title: example
collapsed: true
subDir:
- title: subDir a
path: test
collapsed: true
- title: subDir back
path: test
noScan: true
file: README
---Tip
If you are using the VSCode editor to contribute to this site, you can use our predefined code snippets. For non-object types of configuration fields, you can directly type their names to trigger autocompletion. For the root object and SubDir object, you can use @root and @subdir respectively to trigger the corresponding snippets.
Frontmatter Declaration
At the beginning of each Markdown file, use --- to create frontmatter configuration.
---
# Add your frontmatter here
---
M1hono
skyraah