@modern-js/doc-tools-doc

# Auto Nav/Sidebar In Modern.js Doc, in addition to declaring [nav](/api/config/config-theme.html#nav) and [sidebar](/api/config/config-theme.html#sidebar) through `themeConfig` in the config file, you You can also automatically generate the nav bar and sidebar by declaring the `_meta.json` description file. We recommend the latter because it can make the config file more concise and clear. :::tip Automated navbar/sidebar will only work if there are no `nav` and `sidebar` configurations in the config file `modern.config.ts`. ::: ## Basic Concept First, `_meta.json` can be divided into two categories: navbar level and sidebar level. The difference between the two is that the navigation-level `_meta.json` lives in the document root, while the sidebar-level `_meta.json` lives in a subdirectory of the document root. for example: ```js docs ├── _meta.json // navigation bar level └── guides ├── _meta.json // sidebar level ├── introduction.mdx └── advanced ├── _meta.json // sidebar level └── plugin-development.md ``` If your document supports i18n, then `_meta.json` at the navigation bar level will be placed in the corresponding language directory, for example: ```js docs ├── en │ ├── _meta.json // navigation bar level │ └── guides │ ├── _meta.json // sidebar level │ ├── introduction.mdx │ ├── install.mdx │ └── advanced │ ├── _meta.json // sidebar level │ └── plugin-development.md └── zh ├── _meta.json // navigation bar level └── guides ├── _meta.json // sidebar level ├── introduction.mdx ├── install.mdx └── advanced ├── _meta.json // sidebar level └── plugin-development.md ``` ## Navbar Level Config In the case of the navigation bar level, you can fill in an array in `_meta.json`, and its type is exactly the same as the nav config of the default theme. For details, please refer to [nav config](/api/config/config-theme.html#nav). for example: ```json [ { "text": "Guide", "link": "/guides/introduction", "activeMatch": "^/guides/" } ] ``` ## Sidebar Level Config In the case of the sidebar level, you can fill in `_meta.json` an array with each item of the following type: ```ts export type SideMetaItem = | string | { type: 'file'; name: string; label?: string; } | { type: 'dir'; name: string; label?: string; collapsible?: boolean; collapsed?: boolean; }; ``` ### string When the type is `string`, it means that the item is a file, and the file name is the string, for example: ```json ["introduction"] ``` The file name may or may not have a suffix, for example `introduction` will be parsed as `introduction.mdx`. ### obejct When the type is an object, you can describe it as a file, a directory or a custom link. In the case of describing **file**, the types are as follows: ```ts { type: 'file'; name: string; label?: string; } ``` Among them, `name` means the file name, `with`/`without` suffix is supported, `label` means the display name of the file in the sidebar.`label` is an optional value, if it is not filled, it will automatically take the h1 title in the document. For example: ```json { "type": "file", "name": "introduction", "label": "Introduction" } ``` In the case of describing **directories**, the types are as follows: ```ts { type: 'dir'; name: string; label?: string; collapsible?: boolean; collapsed?: boolean; } ``` Among them, `name` indicates the directory name, `label` indicates the display name of the directory in the sidebar, `collapsible` indicates whether the directory can be collapsed, and `collapsed` indicates whether the directory is collapsed by default, for example: ```json { "type": "dir", "name": "advanced", "label": "Advanced", "collapsible": true, "collapsed": false } ``` In the case of describing **custom link**, the types are as follows: ```ts { type: 'custom-link'; link: string; label: string; } ``` Among them, `link` indicates the link address, `label` indicates the display name of the link in the sidebar, for example: ```json { "type": "custom-link", "link": "/my-link", "label": "My Link" } ``` `link` support external links, for example: ```json { "type": "custom-link", "link": "https://github.com", "label": "GitHub" } ``` ### Complete Example Here is a complete example using the three types above: ```json [ "install", { "type": "file", "name": "introduction", "label": "Introduction" }, { "type": "dir", "name": "advanced", "label": "Advanced", "collapsible": true, "collapsed": false }, { "type": "custom-link", "link": "/my-link", "label": "My Link" } ] ``` ### No Config Usage In some directories, you don't need to configure `_meta.json` and let the framework automatically generate the sidebar. This requires ensuring that the directory contains only documents, not subdirectories, and you have no requirements for the order of documents. For example, there is now the following document structure: ```bash docs ├── _meta.json └── guides ├── _meta.json └── basic ├── introduction.mdx ├── install.mdx └── plugin-development.md ``` In the guides directory you can configure `_meta.json` as follows: ```json [ { "type": "dir", "name": "basic", "label": "Basic", "collapsible": true, "collapsed": false } ] ``` In `basic` directory, you may not configure `_meta.json`, and then the framework will automatically generate a sidebar for you, the default is sorted alphabetically according to the file name. If you want to customize the order, you can prefix the file name with a number, such as: ```bash basic ├── 1-introduction.mdx ├── 2-install.mdx └── 3-plugin-development.md ``` ### Add SVG Icons Before Titles In addition, you can add icons before the title through the `tag` confing, like this: ```json title="_meta.json" { "type": "file", "name": "introduction", "label": "Introduction", "tag": "<svg width=\"1em\" height=\"1em\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M4 6h24v2H4zm0 18h24v2H4zm0-12h24v2H4zm0 6h24v2H4z\"/></svg>" } ``` The value of `tag` is a svg tag string or image url, which you can configure in the **navbar** or **sidebar**.