Zeka Stack 文档

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

快速开始

安装依赖

npm install

开发模式

npm run dev

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

构建文档

npm run build

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

预览构建结果

npm run preview

同步文档

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

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

菜单显示规则

1. 菜单文本：自动使用文档的一级标题（# 后的内容）作为菜单项文本
2. 排序规则：
   • index.md 始终排在最前面（sortKey: 0）
   • 编号文档按数字从小到大排序（如 1, 2, 3...）
   • 无编号文档排到最后（sortKey: 9999）
3. 链接生成：
   • 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 域名。

部署步骤

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

配置说明

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

文档开发规范

如果你需要为本仓库新增或维护文档，请优先阅读以下两份开发者文档：

• docs-sync-guide.md：说明文档应该如何组织、同步、放目录，以及双向链接为什么容易报错
• docs-authoring-best-practices.md：说明文档应该怎么写，包括标题、结构、示例、表格、链接写法和 AI 友好文档建议

这两份文档主要面向参与文档维护的开发者，而不是部署后访问站点的普通用户。

更新时间显示说明

站点页面里的“更新于”来自 VitePress 的 lastUpdated，其时间源是 Git 提交历史。

如果某个 .md 文件没有被 Git 跟踪（例如被 .gitignore 忽略，或新增后未 git add），页面可能出现异常更新时间（例如 1970.01.01）。

建议在排查时先执行：

# 检查文件是否被忽略
git check-ignore -v "path/to/file.md"

# 检查文件是否已纳入版本管理
git status -- "path/to/file.md"

更新时间显示说明

站点页面里的“更新于”来自 VitePress 的 lastUpdated，其时间源是 Git 提交历史。

如果某个 .md 文件没有被 Git 跟踪（例如被 .gitignore 忽略，或新增后未 git add），页面可能出现异常更新时间（例如 1970.01.01）。

建议在排查时先执行：

# 检查文件是否被忽略
git check-ignore -v "path/to/file.md"

# 检查文件是否已纳入版本管理
git status -- "path/to/file.md"

代码图标

使用方式

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

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

图标映射

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',
}

vitepress-plugin-legend

使用方式

# Zeka Stack
## Arco Meta
- 元数据管理
## Blen Kernel
- 认证授权
- 日志系统
## Cubo Starter
- 快速启动器

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    U->>S: 请求登录
    S-->>U: 返回 Token
    U->>S: 携带 Token 请求数据
    S-->>U: 返回用户数据

Loading

徽章

后端技术栈

前端技术栈

DevOps

运维技术栈

测试技术栈

开发工具

其他

GitHub风格警报

[!提醒] 重要 强调用户在快速浏览文档时也不应忽略的重要信息。

[!建议] 有助于用户更顺利达成目标的建议性信息。

[!重要] 对用户达成目标至关重要的信息。

[!警告] 因为可能存在风险，所以需要用户立即关注的关键内容。

[!注意] 行为可能带来的负面影响。

Badge组件

• VitePress
• VitePress
• VitePress
• VitePress

表情

https://www.emojiall.com/zh-hans