VitePress-Helper：优化你的 VitePress 体验

作为一个开发人员，往往会有构建内容站点的需求，比如个人站点、技术文档、博客。

个人常用 VitePress 来实现这个需求，VitePress 是一个很好用的静态文档构建工具。它足够轻、快、易拓展。但使用了一段时间后，感觉在使用体验上还是存在些许优化空间。

VitePress 默认的 导航栏 和 侧边栏 配置比较繁琐，而且配置文件和源码文件是分离的，需要手动同步。在管理的内容数量比较少的情况下，还问题不大，一旦内容数量比较多的话，会增加很多维护成本。

另一方面，作为 VitePress 使用者，可能会有不止一个 VitePress 项目，如果每个项目都配置一遍，也是比较麻烦的。

在发现问题后，检索了关于 VitePress 的插件，可以看出有不少人有相同的感受。尝试了部分插件，并没有很好的解决问题或者说大家关注的细节有所出入。

所以最终决定写一个工具，让自己使用起来更加便利，同时也希望能够帮助大家更轻松地使用 VitePress。

主页：huyikai.github.io/vitepress-h...

Github：github.com/huyikai/vit...

主要功能

CLI：指导完成初始化操作，可以快速创建项目。
导航栏自动生成：根据文件目录自动生成导航栏，支持多级目录，优化了多层级、链接与类目等多种情况下的样式处理。
侧边栏自动生成：根据文件目录自动生成侧边栏。
集成 CMS：运行本地 CMS，使内容管理更加简单。
自定义首页：提供 .vitepress/theme/home.vue 文件，可以根据需要自定义首页的内容和样式。

快速开始

目前提供两种使用方法：

使用脚手架初始化（推荐），可以开箱即用。
shell 复制代码
```
npx @huyikai/vitepress-Helper init
```
在现有的 vitepress 项目中添加 @huyikai/vitepress-Helper 依赖，并手动修改配置和主题。
shell 复制代码
```
npm @huyikai/vitepress-Helper
```
然后修改 config.js 文件，创建 .vitepress/theme 目录，并创建 home.vue 和 index.js 文件。

详细介绍

CLI

指导完成初始化操作，可以快速创建项目。

使用

shell 复制代码

npx @huyikai/vitepress-helper init

将会被问到一些简单的问题：

shell 复制代码

# 项目名称 | Project Name
# 作者 | Author
# 版本号 | Version
# 是否需要本地 CMS ? | Do you need local CMS?

初始化完成后，您可以运行 npm run dev 进行预览，如果 CMS 选择了 yes，则可以运行 npm run cms 进行内容管理。

CMS

运行本地 CMS 以简化内容管理

计划

Markdown 编辑器使用体验优化。
文件、目录移动以及拖拽移动。
本地文件导入、批处理。
链接内容导入。
版本控制。
静态资源（映像）管理。

使用

通过脚手架创建项目时,会询问是否需要添加 CMS，选择 是 在初始化完成后直接运行 npm run cms 即可使用。

后续补充 CMS 功能，需要先运行 npm install @huyikai/local-cms -D 安装依赖，然后在 package.json 的 scripts 中添加脚本命令 "cms": "node node_modules/@huyikai/local-cms/cms.js docs" 再运行 npm run cms 即可。

Tip：脚本命令中的 docs 为 CMS 的执行目录，需要与 VitePress 的执行目录一致，通常情况下这个目录会使用 docs ，可以自定义修改该目录，但是要注意需要同步修改脚本命令和 config.js 中 VitePress-Helper 的初始参数。

Home

在 VitePress 默认主题中，首页样式通过配置 Hero Section 来实现。不少开发者喜欢更具个性化的首页，默认主题不足以满足要求，VitePress 本身提供了自定义主题的方法，但为了让使用者更容易上手，注册了可以直接修改的 Home 组件作为首页，以此方便大家使用。

使用

通过脚手架项目时，会自动创建文件 docs/.vitepress/theme/home.vue。直接在里面按需修改即可。如果想切换回默认主题的首页，则需要将 docs/index.md 文件中的 Frontmatter 中的 layout 字段修改为 home ，然后按照 VitePress 提供的 Hero Section 配置即可。

后续补充 Home 需要先运行 npm install @huyikai/vitepress-helper -D 安装依赖，然后创建 docs/.vitepress/theme/home.vue docs/.vitepress/theme/index.js。同时还需要将文档根目录(docs/index.md)下的 index.md 文件的 Frontmatter 中的 layout 字段修改为 custom。这样运行运行时首页显示的就会是 home.vue 中自定的内容了。

Tip：在 VitePress-Helper 默认添加的home.vue 的文件中，额外添加了一个 VitePress 默认导出的 <VPDoc /> 组件。这样 docs/index.md 文件中的内容会在首页的下方补充渲染。可以根据自身需要取舍这部分。

docs/.vitepress/theme/home.vue

vue 复制代码

<script setup>
...
</script>
<template></template>

docs/.vitepress/theme/index.js

js 复制代码

...
import Home from './home.vue';

const theme = {
  Layout,
  enhanceApp: ({ app }: any) => {
    ...
    app.component('Home', Home);
  }
};
export default theme;

docs/index.md

yaml 复制代码

---
layout: custom
aside: false
outline: false
lastUpdated: false
---

Nav

根据 VitePress 运行目录下的目录及内容自动生成导航栏

使用

通过脚手架创建项目时，config.js 中已默认配置好导航栏相关配置。直接使用即可。

后续补充导航栏自动生成的功能，需要先运行 npm install @huyikai/vitepress-helper -D 安装依赖，然后修改 docs/.vitepress/config.js 中的配置。

js 复制代码

import vitepressHelper from '@huyikai/vitepress-helper';
export default async () => {
  const instance: any = await vitepressHelper({
    directory: 'docs',
    collapsible: true
  });
  return{
    ...
    nav: instance.nav,
  }
};

也可以根据自审需求，扩展 nav。

js 复制代码

export default () => {
  return {
    nav: [
      ...instance.nav,
      { text: 'other', link: 'https://github.com/huyikai/vitepress-helper' },
      { text: 'others', items:[...] }
    ]
  };
};

根据 VitePress 运行目录下的目录及内容自动生成侧边栏

使用

通过脚手架创建项目时，config.js 中已默认配置好侧边栏栏相关配置。直接使用即可。

后续补充侧边栏栏自动生成的功能，需要先运行 npm install @huyikai/vitepress-helper -D 安装依赖，然后修改 docs/.vitepress/config.js 中的配置。

js 复制代码

import vitepressHelper from '@huyikai/vitepress-helper';
export default async () => {
  const instance: any = await vitepressHelper({
    directory: 'docs',
    collapsible: true
  });
  return{
    ...
    sidebar: instance.sidebar,
  }
};

整体的未来计划

未来计划进行以下改进：

代码质量：添加单元测试以确保代码质量。
用户体验：优化 UI、使用逻辑和性能。
文档：提供双语文档、更详细的使用说明和适当的使用示例。

后续也会继续关注 VitePress 的更新，保持功能和体验的同步，并在开发和使用过程中探究新的灵感。

结尾

如果感觉有点意思麻烦帮忙点个start，在此抛砖引玉也希望获得大家的反馈和指导，有兴趣的话也欢迎一同参与开发。

最后欢迎大家使用 VitePress-Helper，希望它能帮助你更轻松地使用 VitePress，成为你工作和学习中的得力助手。

关于快速构建内容站点之 Vitepress 的优化插件 Vitepress-Helper

VitePress-Helper：优化你的 VitePress 体验

主要功能

快速开始

详细介绍

CLI

使用

CMS

相关信息

计划

使用

更多关于 CMS

Home

使用

docs/.vitepress/theme/home.vue

docs/.vitepress/theme/index.js

docs/index.md

Nav

使用

Sidebar

使用

整体的未来计划

结尾