refactor: 💡 refactor theme

docs/.vitepress/config.ts

@@ -1,4 +1,7 @@
-import vitepressHelper from '@huyikai/vitepress-helper';
+import vitepressHelper, { config } from '@huyikai/vitepress-helper';
+
+import { defineConfigWithTheme } from 'vitepress';
+
 const vitepressHelperConfig = {
   directory: 'docs',
   collapsible: true
@@ -71,5 +74,5 @@ export default async () => {
     ...vitepressHelperConfig,
     ...vitepressConfig
   });
-  return instance;
+  return defineConfigWithTheme({ extends: config, ...instance });
 };

docs/.vitepress/theme/index.ts

@@ -1,21 +1,9 @@
-import 'vitepress/dist/client/theme-default/styles/vars.css';
-import 'vitepress/dist/client/theme-default/styles/base.css';
-import 'vitepress/dist/client/theme-default/styles/utils.css';
-import 'vitepress/dist/client/theme-default/styles/components/custom-block.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-code.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-code-group.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-doc.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-sponsor.css';
-
 import Home from './home.vue';
-import Layout from '@huyikai/vitepress-helper/theme/Theme.vue';
-import VPBadge from 'vitepress/dist/client/theme-default/components/VPBadge.vue';
+import theme from '@huyikai/vitepress-helper/theme/index';
 
-const theme = {
-  Layout,
-  enhanceApp: ({ app }: any) => {
+export default {
+  extends: theme,
+  enhanceApp: ({ app }) => {
     app.component('Home', Home);
-    app.component('Badge', VPBadge);
   }
 };
-export default theme;

docs/Guide/Basic/2.GettingStart.md

@@ -1,18 +1,132 @@
 # 快速开始
 
-## 安装向导
+## 安装
+
+### 先决条件
+
+- Node.js 版本需为 18 或更高。
+- 安装到现有项目需要基于 [email protected]或更高。
+
+### 安装方式
+
+VitePress-Helper 支持两种安装方式：
+
+- 在命令行运行安装向导
+- 直接安装到现有项目中，然后手动修改设置(config.js)和主题(theme)。
+
+#### 安装向导
 
 ```shell
 npx @huyikai/vitepress-helper init
+# or
+npm install -g @huyikai/vitepress-helper
+vitepress-helper init
 ```
 
 将会被问到一些简单的问题：
 
 ```shell
-# 项目名称 | Project Name
-# 作者 | Author
-# 版本号 | Version
-# 是否需要本地 CMS ? | Do you need local CMS?
+# Project Name
+# Author
+# Version
+# Do you need local CMS?
+```
+
+#### 安装到现有项目
+
+```shell
+npm i @huyikai/vitepress-helper -D
+npm i vue
+npm i @huyikai/local-cms
 ```
 
-初始化完成后，您可以运行 `npm run dev` 进行预览，如果 CMS 选择了 yes，则可以运行 `npm run cms` 进行内容管理。
+:::tip
+因为 VitePress-Helper 中添加了 `home.vue` 这个自定义首页组件，所以需要安装对等依赖 Vue。如果不需要自定义首页，则可以不安装，并且后续无需创建 `home.vue` 文件。
+
+如果需要本地 cms 功能，则需要安装 `@huyikai/local-cms`。
+:::
+
+修改 config.js
+
+```javascript
+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`
+
+```vue
+<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>
+```
+
+```javascript
+import Home from './home.vue';
+import theme from '@huyikai/vitepress-helper/theme/index';
+
+export default {
+  extends: theme,
+  enhanceApp: ({ app }: any) => {
+    app.component('Home', Home);
+  }
+};
+```
+
+## 启动和运行
+
+安装向导会自动注入以下脚本到您的 `package.json`，如果是安装到现有项目，请确认 `package.json` 中有以下脚本
+
+```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](https://vitepress.dev/reference/cli#vitepress-dev))。
+
+`npm run build`：构建用于生产的 VitePress 站点([vitepress-build](https://vitepress.dev/reference/cli#vitepress-build))。
+
+`npm run cms`：启动本地 CMS 服务器。

packages/@huyikai/vitepress-helper/package.json

@@ -20,16 +20,22 @@
   "author": "huyikai",
   "type": "module",
   "main": "lib/index.esm.js",
+  "types": "lib/types/src/index.d.ts",
   "module": "lib/index.esm.js",
-  "types": "lib/types/index.d.ts",
   "bin": {
     "vitepress-helper": "./lib/bin/index.js"
   },
+  "exports": {
+    ".": {
+      "types": "./lib/types/src/index.d.ts",
+      "default": "./lib/index.esm.js"
+    },
+    "./theme/*": "./theme/*"
+  },
   "files": [
     "lib",
     "template",
-    "theme",
-    "bin"
+    "theme"
   ],
   "scripts": {
     "build": "rollup --config rollup.config.ts --configPlugin typescript",
@@ -64,7 +70,7 @@
     "typescript": "^5.0.4"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "publishConfig": {
     "access": "public",

packages/@huyikai/vitepress-helper/rollup.config.ts

@@ -3,7 +3,8 @@ import { fileURLToPath } from 'url';
 import fs from 'fs';
 import path from 'path';
 import terser from '@rollup/plugin-terser';
-import typescript from '@rollup/plugin-typescript';
+import typescript from 'rollup-plugin-typescript2';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const replaceVersion = () => {
   const packageJson = JSON.parse(
@@ -48,7 +49,7 @@ export default [
     ],
     plugins: [
       replaceVersion(),
-      typescript({ tsconfig: 'bin/tsconfig.json' }),
+      typescript(),
       terser(),
       addShebang({ include: 'lib/bin/index.js' })
     ]

packages/@huyikai/vitepress-helper/src/config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from 'vitepress'
+export default defineConfig({
+  title: 'vitepres-helper',
+  description: 'vitepres-helper.',
+  head: [
+    ['link', { rel: 'icon', href: '/vitepress-helper/favicon.ico' }] //浏览器标签icon
+  ],
+  themeConfig: {
+    siteTitle: 'VitePress-Helper', //导航栏左侧名称
+    logo: '/static/nav-logo.svg', //导航栏左侧头像
+    outlineTitle: 'Catalog', //右侧 侧边栏标题
+    search: {
+      provider: 'local' // 离线搜索
+    },
+    // 导航栏
+    nav: [
+      {
+        text: 'test',
+        link: 'https://huyikai.xyz'
+      }
+    ]
+  }
+});

packages/@huyikai/vitepress-helper/src/index.ts

@@ -1,6 +1,7 @@
-import init from './init';
-import nav from './nav';
-import pages from './pages';
-import sidebar from './sidebar';
-export { pages, nav, sidebar, init };
-export default init;
+export { default as init } from './init';
+export { default as nav } from './nav';
+export { default as pages } from './pages';
+export { default as sidebar } from './sidebar';
+export { default as config } from './config';
+// export { default as theme } from './../theme';
+export { default } from './init';

packages/@huyikai/vitepress-helper/src/init.ts

@@ -1,7 +1,7 @@
-import fetchAllPages from "./pages";
-import locales from "./locales";
-import nav from "./nav";
-import sidebar from "./sidebar";
+import fetchAllPages from './pages';
+import locales from './locales';
+import nav from './nav';
+import sidebar from './sidebar';
 
 export default async (params: any) => {
   const pages: any = await fetchAllPages(params);
@@ -11,7 +11,7 @@ export default async (params: any) => {
     ? {
         ...params?.themeConfig,
         nav: [...nav(baseParams), ...(params?.themeConfig?.nav || [])],
-        sidebar: sidebar(baseParams),
+        sidebar: sidebar(baseParams)
       }
     : undefined;
   return {
@@ -20,6 +20,6 @@ export default async (params: any) => {
     pages: pages.basePages,
     ...params,
     themeConfig,
-    locales: locales(localesParams),
+    locales: locales(localesParams)
   };
 };

packages/@huyikai/vitepress-helper/template/docs/.vitepress/config.ts

@@ -1,4 +1,7 @@
-import vitepressHelper from '@huyikai/vitepress-helper';
+import vitepressHelper, { config } from '@huyikai/vitepress-helper';
+
+import { defineConfigWithTheme } from 'vitepress';
+
 const vitepressHelperConfig = {
   directory: 'docs',
   collapsible: true
@@ -53,5 +56,5 @@ export default async () => {
     ...vitepressHelperConfig,
     ...vitepressConfig
   });
-  return instance;
+  return defineConfigWithTheme({ extends: config, ...instance });
 };

packages/@huyikai/vitepress-helper/template/docs/.vitepress/theme/index.ts

@@ -1,21 +1,9 @@
-import 'vitepress/dist/client/theme-default/styles/vars.css';
-import 'vitepress/dist/client/theme-default/styles/base.css';
-import 'vitepress/dist/client/theme-default/styles/utils.css';
-import 'vitepress/dist/client/theme-default/styles/components/custom-block.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-code.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-code-group.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-doc.css';
-import 'vitepress/dist/client/theme-default/styles/components/vp-sponsor.css';
-
 import Home from './home.vue';
-import Layout from '@huyikai/vitepress-helper/theme/Theme.vue';
-import VPBadge from 'vitepress/dist/client/theme-default/components/VPBadge.vue';
+import theme from '@huyikai/vitepress-helper/theme/index';
 
-const theme = {
-  Layout,
+export default {
+  extends: theme,
   enhanceApp: ({ app }: any) => {
     app.component('Home', Home);
-    app.component('Badge', VPBadge);
   }
 };
-export default theme;

packages/@huyikai/vitepress-helper/theme/Layout.vue

@@ -8,7 +8,7 @@ import VPLocalNav from 'vitepress/dist/client/theme-default/components/VPLocalNa
 import VPNav from './components/VPNav.vue'
 import VPSidebar from 'vitepress/dist/client/theme-default/components/VPSidebar.vue'
 import VPSkipLink from 'vitepress/dist/client/theme-default/components/VPSkipLink.vue'
-import { useData } from 'vitepress/dist/client/theme-default/composables/data'
+import { useData } from 'vitepress'
 import { useCloseSidebarOnEscape, useSidebar } from 'vitepress/dist/client/theme-default/composables/sidebar'
 
 const {