Zeka Stack 文档

更新:2025-09-20

字数:0 字

时长:0 分钟

阅读:--次

基于 VitePress 的 Zeka Stack 框架文档站点。

快速开始

安装依赖

bash

npm install

开发模式

bash

npm run dev

访问 http://localhost:5173 查看文档。

构建文档

bash

npm run build

构建后的文件在 .vitepress/dist 目录。

预览构建结果

bash

npm run preview

同步文档

当子模块的 README.md 或图片资源更新后，需要同步到 docs 目录：

bash

npm run sync
# 或者
bash sync-docs.sh

同步脚本会自动：

复制 README.md 到对应的 index.md
复制 imgs/ 目录下的所有图片资源
保持相对路径不变（./imgs/xxx.webp 在 VitePress 中能正常显示）

文档结构

index.md - 首页
guide/ - 简介相关文档目录
arco-meta/ - Arco Meta 模块文档
blen-kernel/ - Blen Kernel 模块文档
cubo-starter/ - Cubo Starter 模块文档
cubo-starter-examples/ - Cubo Examples 模块文档

Guide 目录多文档菜单

guide 目录支持多个文档文件，所有文档会自动显示在侧边栏的"简介"菜单下。

文件命名规则

在 guide 目录下创建文档时，使用编号前缀来控制菜单顺序：

index.md - 主文档，链接为 /guide/，始终排在最前面
1.introduction.md - 编号文档，链接为 /guide/1.introduction，按编号排序
2.quick-start.md - 编号文档，链接为 /guide/2.quick-start，按编号排序
3.resources.md - 编号文档，链接为 /guide/3.resources，按编号排序
other.md - 无编号文档，链接为 /guide/other，排在所有编号文档之后

目录结构示例

docs/guide/
├── index.md              # Zeka Stack 简介 (排序: 0, 链接: /guide/)
├── 1.introduction.md     # 简介 (排序: 1, 链接: /guide/1.introduction)
├── 2.quick-start.md      # 快速上手 (排序: 2, 链接: /guide/2.quick-start)
├── 3.resources.md        # 资源汇总 (排序: 3, 链接: /guide/3.resources)
└── imgs/                 # 图片资源目录
    └── example.webp

菜单显示规则

菜单文本：自动使用文档的一级标题（# 后的内容）作为菜单项文本
排序规则：
- index.md 始终排在最前面（sortKey: 0）
- 编号文档按数字从小到大排序（如 1, 2, 3...）
- 无编号文档排到最后（sortKey: 9999）
链接生成：
- index.md → /guide/
- 1.introduction.md → /guide/1.introduction
- 2.quick-start.md → /guide/2.quick-start

示例

侧边栏中的"简介"菜单将显示：

简介
  ├─ Zeka Stack 简介        (来自 index.md)
  ├─ 简介                   (来自 1.introduction.md)
  ├─ 快速上手               (来自 2.quick-start.md)
  └─ 资源汇总               (来自 3.resources.md)

注意事项

文档的一级标题（# 标题）将作为菜单项文本
文件名中的编号用于排序，不会出现在链接中
所有图片资源建议放在 guide/imgs/ 目录下，使用 WebP 格式

模块 docs 目录多文档菜单

模块的 docs/ 目录支持多个文档文件，这些文档会自动显示在对应模块的子菜单中。

文件命名规则

在模块的 docs/ 目录下创建文档时，使用编号前缀来控制菜单顺序：

1.文件名.md - 编号文档，按编号排序
2.文件名.md - 编号文档，按编号排序
文件名.md - 无编号文档，排在所有编号文档之后

如何新增目录和文档

两种目录类型

文档目录分为两种类型：

1. 模块目录（自动同步）

这些目录会从源码目录自动同步到文档目录。

特点：

📁 文档位置：源码目录下的 README.md
🔄 同步方式：运行 npm run sync 或 bash sync-docs.sh 自动同步
📋 菜单生成：自动根据模块分类到对应的菜单
✏️ 维护方式：只需修改源码目录中的 README.md，然后同步即可

2. 非模块目录（手动维护）

目录名不以数字开头（如 guide、about），这些目录需要在 docs/ 目录下手动维护。

特点：

📁 文档位置：直接在 docs/ 目录下（如 docs/guide/index.md）
🔄 同步方式：手动创建和编辑文档
📋 菜单生成：需要在 config.js 中使用 addDirectoryMenu() 函数添加
✏️ 维护方式：直接在 docs/ 目录下创建和编辑文档

已支持的目录：

guide/ - 简介相关文档
about/ - 关于项目文档

部署

文档部署到 zeka-stack.dong4j.site 域名。

部署步骤

构建文档：npm run build
将 .vitepress/dist 目录内容部署到服务器
配置 Nginx 或其他 Web 服务器指向该目录

配置说明

.vitepress/config.js - VitePress 配置文件
sync-docs.sh - 文档同步脚本

代码图标

使用方式

vite.config.js

import legacy from '@vitejs/plugin-legacy'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11'],
    }),
  ],
})

图标映射

javascript

export const builtinIcons = {
  // package managers
  'pnpm': 'vscode-icons:file-type-light-pnpm',
  'npm': 'vscode-icons:file-type-npm',
  'yarn': 'vscode-icons:file-type-yarn',
  'bun': 'vscode-icons:file-type-bun',
  'deno': 'vscode-icons:file-type-deno',
  // frameworks
  'vue': 'vscode-icons:file-type-vue',
  'svelte': 'vscode-icons:file-type-svelte',
  'angular': 'vscode-icons:file-type-angular',
  'react': 'vscode-icons:file-type-reactjs',
  'next': 'vscode-icons:file-type-light-next',
  'nuxt': 'vscode-icons:file-type-nuxt',
  'solid': 'logos:solidjs-icon',
  'astro': 'vscode-icons:file-type-light-astro',
  'qwik': 'logos:qwik-icon',
  'ember': 'vscode-icons:file-type-ember',
  // bundlers
  'rollup': 'vscode-icons:file-type-rollup',
  'webpack': 'vscode-icons:file-type-webpack',
  'vite': 'vscode-icons:file-type-vite',
  'esbuild': 'vscode-icons:file-type-esbuild',
  // configuration files
  'package.json': 'vscode-icons:file-type-node',
  'tsconfig.json': 'vscode-icons:file-type-tsconfig',
  '.npmrc': 'vscode-icons:file-type-npm',
  '.editorconfig': 'vscode-icons:file-type-editorconfig',
  '.eslintrc': 'vscode-icons:file-type-eslint',
  '.eslintignore': 'vscode-icons:file-type-eslint',
  'eslint.config': 'vscode-icons:file-type-eslint',
  '.gitignore': 'vscode-icons:file-type-git',
  '.gitattributes': 'vscode-icons:file-type-git',
  '.env': 'vscode-icons:file-type-dotenv',
  '.env.example': 'vscode-icons:file-type-dotenv',
  '.vscode': 'vscode-icons:file-type-vscode',
  'tailwind.config': 'vscode-icons:file-type-tailwind',
  'uno.config': 'vscode-icons:file-type-unocss',
  'unocss.config': 'vscode-icons:file-type-unocss',
  '.oxlintrc': 'vscode-icons:file-type-oxlint',
  'vue.config': 'vscode-icons:file-type-vueconfig',
  // filename extensions
  '.mts': 'vscode-icons:file-type-typescript',
  '.cts': 'vscode-icons:file-type-typescript',
  '.ts': 'vscode-icons:file-type-typescript',
  '.tsx': 'vscode-icons:file-type-typescript',
  '.mjs': 'vscode-icons:file-type-js',
  '.cjs': 'vscode-icons:file-type-js',
  '.json': 'vscode-icons:file-type-json',
  '.js': 'vscode-icons:file-type-js',
  '.jsx': 'vscode-icons:file-type-js',
  '.md': 'vscode-icons:file-type-markdown',
  '.py': 'vscode-icons:file-type-python',
  '.ico': 'vscode-icons:file-type-favicon',
  '.html': 'vscode-icons:file-type-html',
  '.css': 'vscode-icons:file-type-css',
  '.scss': 'vscode-icons:file-type-scss',
  '.yml': 'vscode-icons:file-type-light-yaml',
  '.yaml': 'vscode-icons:file-type-light-yaml',
  '.php': 'vscode-icons:file-type-php',
  '.gjs': 'vscode-icons:file-type-glimmer',
  '.gts': 'vscode-icons:file-type-glimmer',
}