开发了一个vitepress使用助手

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

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

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

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

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

所以最终决定写一个工具，能够增强使用体验的同时保留本身的扩展性。在让自己使用起来更加便利，同时也希望能够帮助大家更轻松地使用 VitePress。

工具主页：huyikai.github.io/vitepress-h…

Github：github.com/huyikai/vit…

使用案例：Tree-Conver、Local-CMS

快速开始

安装

前提条件

• Node.js 版本需为 18 或更高。
• 安装到现有项目需要基于 vitepress@1.0.0-rc.31或更高。

安装方式

VitePress-Helper 支持两种安装方式：

• 在命令行运行安装向导
• 直接安装到现有项目中，然后手动修改设置(config.js)和主题(theme)。

安装向导

npx @huyikai/vitepress-helper init
# or
npm install -g @huyikai/vitepress-helper
vitepress-helper init

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

# Project Name
# Author
# Version
# Do you need local CMS?

安装到现有项目

npm i @huyikai/vitepress-helper -D
npm i vue
npm i @huyikai/local-cms

:::tip 因为 VitePress-Helper 中添加了 home.vue 这个自定义首页组件，所以需要安装对等依赖 Vue。如果不需要自定义首页，则可以不安装，并且后续无需创建 home.vue 文件。

如果需要本地 cms 功能，则需要安装 @huyikai/local-cms。 :::

修改 config.js

import vitepressHelper, { config } from '@huyikai/vitepress-helper';
import { defineConfigWithTheme } from 'vitepress';

// vitepress-helper default setting
const vitepressHelperConfig = {
  directory: 'docs',
  collapsible: true
};

// vitepres default setting
const vitepressConfig={
  title:'your site title',
  description:'your site description',
  themeconfig:{
    ...
  },
  ...
}

export default async () => {
  const vitepressHelperInstance = await vitepressHelper({
    ...vitepressHelperConfig,
    ...vitepressConfig
  });
  return defineConfigWithTheme({
    extends: config,
    ...vitepressHelperInstance
  });
};

新建目录 .vitepress/theme ，在目录下新建文件 home.vue、index.js

<script setup lang="ts">
import VPDoc from 'vitepress/dist/client/theme-default/components/VPDoc.vue';
import VPButton from 'vitepress/dist/client/theme-default/components/VPButton.vue';
</script>
<template>
  <!-- 可以自定义任意内容，例： -->
  <div>你的自定义主页内容</div>

  <!-- 此处的 VPDoc 组件将会渲染显示 docs 根目录中 index.md 中的内容。 -->
  <VPDoc />
</template>
<style></style>

import Home from './home.vue';
import theme from '@huyikai/vitepress-helper/theme/index';

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

启动和运行

安装向导会自动注入以下脚本到您的 package.json，如果是安装到现有项目，请确认 package.json 中有以下脚本

{
  ...
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "cms": "node node_modules/@huyikai/local-cms/cms.js docs",
  },
  ...
}

npm run dev：启动一个本地开发服务器(vitepress-dev)。

npm run build：构建用于生产的 VitePress 站点(vitepress-build)。

npm run cms：启动本地 CMS 服务器。

详细介绍

CLI

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

使用

npx @huyikai/vitepress-helper init

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

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

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

CMS

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

相关信息

• UI 基于 Antdv。
• 通过脚本运行。
• 通过运行本地node服务，对目录和文件实现基础的增删改查功能。
• Markdown 文件的编辑，实时预览保存。

计划

• 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 的初始参数。

更多关于 CMS

开发这个 本地CMS，是因为在使用过程中发现，即使有了导航栏和侧边栏的工具，但仍然存在一些维护成本，比如需要在开发工具中管理内容及目录，又要在 markdown 编辑器中编辑内容。想进一步简化这个过程的操作，更加专注于内容的创作和管理。

VitePress 是一个静态站点生成器，常见的使用方式是编辑内容然后将代码推送到代码仓库，通过代码仓库的 Pages 和工作流自动发布站点。也可以在服务器上直接放置构建后的代码文件或者通过容器部署。

CMS 系统有很多已经成熟的项目，之所以选择开发一个简单的本地 CMS ，而不是使用现有 CMS 系统的原因如下。

目前了解的大多数 CMS 系统需要服务器和数据库来搭配对内容管理和存储。 这种使用方式比较成熟，但对于当前的使用场景来说，体量过重了，增加额外的开发成本、使用成本。和 VitePress 的使用体验也有所割裂，通过 CMS 提供的接口获取内容对 SEO 也不够友好。 最主要的它们往往还需要额外付费订阅才能使用。

还有一种基于 Git 的 CMS 管理系统，相比较更适合，但也存在使用成本和体验的问题。当然这并不是这些 CMS 系统的问题，只是使用场景没有契合。

所以我认为在使用 VitePress 的场景下需要的是一个使用简单，没有太多概念和配置，甚至用起来像一个 markdown 编辑器的本地 CMS。

VitePress-Helper 中的 CMS 实际上是一个独立开发的库，让 VitePress 更加灵活的同时，也为了方便其他情况下使用，所以将 CMS 独立了出来。

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

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

docs/.vitepress/theme/index.js

import Home from './home.vue';
import theme from '@huyikai/vitepress-helper/theme/index';

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

docs/index.md

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

Nav

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

使用

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

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

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

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

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

Sidebar

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

使用

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

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

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

国际化

vitepress 的国际化需要为语言单独配置导航栏、侧边栏。

import { defineConfig } from 'vitepress'

export default defineConfig({
    ...
    locales: {
    en: {
      label: 'English',
      lang: 'en',
      themeconfig:{
          nav:...,
          sidebar:...
      }
    }
  }
})

在 VitePress-Helper 中只需要配置国际化基础选项即可自动生成对应的导航栏和侧边栏。

import { defineConfig } from 'vitepress'

export default defineConfig({
    ...
    locales: {
    en: {
      label: 'English',
      lang: 'en'
    }
  }
})

整体的未来计划

未来计划进行以下改进：

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

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

结尾

如果它对您有用，请帮忙点个 ⭐️ star，在此抛砖引玉也希望获得大家的反馈和指导，有兴趣的话也欢迎一同参与开发。

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