快速开始

安装

前提条件

• 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 服务器。