title: 项目使用说明
lang: zh-CN
项目介绍
公司处于统一管理文档的目的,希望可以搭建一个ReadMe在线管理查看文档,故采用VitePress搭建,由于维护人员对代码不太理解,所以为了方便他们对文件的创建,以及代码中的必要配置,通过Plopfile.js命令行的方式指导创建
主要目录结构
|—— docs //项目文档目录
| |——.vitepress //vitepress配置目录
| |——guide // /guide/路径下md文件目录
|—— index.md //首页加载Md
Config配置
打开.vitepress/config.js
可看到代码结构如下:
module.exports = {
title: "项目文档", // 顶部左侧标题
base: "/doc/", // 项目的根路径(会自动匹配跟路径下的index.md文档作为首页内容)
head: [
// 设置 描述 和 关键词
[
"meta",
{ name: "keywords", content: "" },
],
],
themeConfig: {
nav: [
// 顶部右侧导航栏
{
text: "项目列表", //菜单名字
items: [ //子菜单项
{ text: "开始使用", //菜单名
link: "/oms/index", //md文档路径
activeMatch: "" // 需要被高亮的 nav 。
},
],
},
],
sidebar: {
// 侧边栏
"/oms/": [ //路径与nav link路径匹配,匹配成功则显示对应的左侧侧边栏
{
text: "文件列表",
collapsable: true,
items: [
{ text: "文件A", link: "/oms/docA" }
],
},
],
},
},
};
使用plop快速创建新菜单
如果需要快捷创建新菜单在命令行输入以下命令
npm run gen:add-menu
会出现以下提示内容
请输入新增菜单名(会根据菜单名建立对应的文件夹以及文件名):
是否需要生成对应菜单栏侧边栏目录?
请输入一级名称:
请输入二级名称:
根据提示输入新建的Menu名称,以及是否需要生成侧边栏菜单,若需要创建侧边栏菜单,则还需要创建对应的一级侧边栏名称和二级侧边栏名称
使用plop快速创建新文件
如果需要快捷创建新文件在命令行输入以下命令
npm run gen:add-file
会出现以下提示内容
请输入想要创建的文件路径(例:/mds/sidebar):
请输入想要创建的文件名(例:test)
文件夹以docs为根路径,输入路径从菜单名开始,例:oms/test
,即会在oms文件夹下创建test文件夹。
文件夹名称test
,即会在oms/test/
路径下创建test.md
文件
通过更改Config.js配置菜单项
在 .vitepress/config.js
中的nav
数组中项目列表
中的items
下添加一个菜单项MDS
,并设置link为guide/mdsDoc
如下:
{
text: "项目列表",
items: [
{
text: "OMS",
link: "/oms/index",
activeMatch: ""
},
{
text: "MDS", //菜单名
link: "/mds/index", //md文档路径
activeMatch: "" // 需要被高亮的 nav 。
},
],
},
根据linkoms/index
需要在doc
文件夹下创建文件夹oms
,并创建index.md
文件,文件夹结构如下
|—— docs //项目文档目录
| |——oms // /guide/路径下md文件目录
| | |—— index.md// /guide/路径下md文件目录
| |——mds
| | |—— index.md
|—— index.md //首页加载Md
……
通过更改Config.js配置侧边栏
若需要显示侧边栏,则只需要在.vitepress/config.js
中的sidebar
对象中添加对应路径的对象,如下
"/mds/": [ //路径与nav link路径匹配,匹配成功则显示对应的左侧侧边栏
{
text: "文件列表",
collapsed: false,//是否默认折叠(若不写该属性则不可折叠,写了该属性则可这点,true or false决定默认折叠状态)
items: [
{ text: "文件A", link: "/mds/docA" }
],
},
],