Quick Start

Installation

Prerequisites

• Node.js version must be 18 or higher.
• Installation to an existing project requires based on vitepress@1.0.0-rc.31 or higher.

Installation Methods

VitePress-Helper supports two installation methods:

• Run the installation wizard in the command line
• Install directly into an existing project, then manually modify the settings (config.js) and theme.

Installation Wizard

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

You will be asked some simple questions:

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

Install to an Existing Project

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

TIP

Because VitePress-Helper has added a custom homepage component home.vue, you need to install the peer dependency Vue. If you don't need a custom homepage, you can skip the installation and you don't need to create a home.vue file later.

If you need the local CMS feature, you need to install @huyikai/local-cms.

Modify 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
  });
};

Create a new directory .vitepress/theme, and create files home.vue and index.js in the directory.

<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>
  <!-- You can customize any content, for example: -->
  <div>Your custom homepage content</div>

  <!-- The VPDoc component here will render and display the content in index.md in the docs root directory. -->
  <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);
  }
};

Start and Run

The installation wizard will automatically inject the following scripts into your package.json. If you are installing to an existing project, please make sure the following scripts are in your package.json.

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

npm run dev: Start a local development server (vitepress-dev).

npm run build: Build a VitePress site for production (vitepress-build).

npm run cms: Start a local CMS server.