Skip to content

Commit a763564

Browse files
h7mlh7ml
committed
docs: 完成文档 v2.0 标准化重构
### 主要更新 1. 文档修复与优化 - 修复 sidebar Ecosystem 链接错误 - 更新组合数量 88→96 种（12前端 × 8后端） - 补全 combinations.md 缺失章节 - 添加 Fresh 到组合矩阵 2. 文档翻译补全（6个文档对） - Nuxt: 366→822行 - Astro: 357→844行 - Solid.js: 501→2621行 - Remix: 598→1531行 - Spring Boot: 720→1723行 - Go Fiber: 754→779行 3. 模版升级 v2.0 - 更新 FRONTEND_TEMPLATE.md（新增10章节） - 更新 BACKEND_TEMPLATE.md（新增8章节） - 创建 README.md v2.0 标准文档 4. v2.0 重构（22个文档对 = 44文件） - 前端13个：Next.js, React, Vue, Angular, Nuxt, SvelteKit, Astro, Solid.js, Qwik, Remix, Preact, Lit, Fresh - 后端9个：NestJS, Node.js, FastAPI, Spring Boot, Go Fiber, PHP, Bun, Deno, BFF 5. 格式统一 - 所有文档副标题添加 HaloLight 前缀 - 统一章节命名规范（特性、核心特性、核心功能等） - 标准化表格格式（技术栈、演示账号、页面路由、环境变量） 6. SEO 优化 - 创建 SeoMeta.vue 组件 - 集成到 VitePress 主题 - 自动生成 TDK + OG 标签 7. 错误修复 - 修复 netlify.md Vue 编译错误 - 修复 fly.md 转义字符问题 - 修复 SeoMeta.vue ESLint 错误 ### v2.0 新增标准章节 前端模版新增： - 特性列表（emoji功能清单） - 核心特性（精简描述） - 环境要求 - 演示账号表格 - 主题系统（皮肤预设+CSS变量） - 环境变量独立章节 - 测试章节 - 配置章节 - CI/CD 工作流 - 高级功能 - 性能优化 - FAQ 后端模版新增： - 特性列表 - 测试章节 - 性能指标 - 可观测性 - FAQ - 开发工具 - Docker Compose配置 ### 统计数据 - 修改文件：76个 - 新增代码：+36,667行 - 删除代码：-13,005行 - 净增加：23,662行 - Agents使用：~25M tokens ### 验证通过 - ✅ pnpm lint - ✅ pnpm build - ✅ 所有文档符合 v2.0 标准
1 parent 8503d1d commit a763564

74 files changed

Lines changed: 36594 additions & 12932 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ node_modules
44
dist
55
.DS_Store
66
*.local
7+
.templates/

‎.vitepress/components/SeoMeta.vue‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
<script setup lang="ts">
2+
import { computed } from 'vue'
3+
import { useData, useRoute } from 'vitepress'
4+
5+
const { page, frontmatter, site } = useData()
6+
const route = useRoute()
7+
8+
// 从文档中提取信息
9+
const pageTitle = computed(() => {
10+
// 优先使用 frontmatter.title，否则从 page.title 获取
11+
return frontmatter.value.title || page.value.title || '文档'
12+
})
13+
14+
const pageDescription = computed(() => {
15+
// 优先使用 frontmatter.description
16+
if (frontmatter.value.description) {
17+
return frontmatter.value.description
18+
}
19+
20+
// 从页面内容中提取第一段文字（去除标题后的第一个段落）
21+
const content = page.value.content || ''
22+
const lines = content.split('\n')
23+
24+
// 找到第一个非标题的段落
25+
for (const line of lines) {
26+
const trimmed = line.trim()
27+
if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('**') && trimmed.length > 20) {
28+
// 移除 markdown 语法
29+
return trimmed
30+
.replace(/\*\*/g, '')
31+
.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
32+
.replace(/`([^`]+)`/g, '$1')
33+
.substring(0, 160)
34+
}
35+
}
36+
37+
return site.value.description || '多框架全栈管理后台'
38+
})
39+
40+
const pageKeywords = computed(() => {
41+
// 从路径和标题中提取关键词
42+
const path = route.path
43+
const keywords: string[] = []
44+
45+
// 从路径提取
46+
if (path.includes('/guide/')) {
47+
keywords.push('教程', '指南', 'guide')
48+
}
49+
if (path.includes('/development/')) {
50+
keywords.push('开发', '架构', 'development', 'architecture')
51+
}
52+
if (path.includes('/api-')) {
53+
keywords.push('API', '后端', 'backend')
54+
}
55+
56+
// 从标题提取框架名称
57+
const title = pageTitle.value.toLowerCase()
58+
const frameworks = ['next.js', 'vue', 'react', 'angular', 'nuxt', 'svelte', 'astro', 'solid', 'remix', 'qwik', 'preact', 'lit', 'fresh']
59+
frameworks.forEach(fw => {
60+
if (title.includes(fw)) {
61+
keywords.push(fw)
62+
}
63+
})
64+
65+
const backends = ['nestjs', 'fastapi', 'spring boot', 'go', 'php', 'bun', 'deno']
66+
backends.forEach(be => {
67+
if (title.includes(be)) {
68+
keywords.push(be)
69+
}
70+
})
71+
72+
// 通用关键词
73+
keywords.push('HaloLight', '管理后台', 'Admin Dashboard', 'TypeScript')
74+
75+
return frontmatter.value.keywords || keywords.join(', ')
76+
})
77+
78+
const fullTitle = computed(() => {
79+
const brandName = site.value.title || 'HaloLight'
80+
return `${pageTitle.value} - ${brandName}`
81+
})
82+
83+
const ogImage = computed(() => {
84+
return frontmatter.value.ogImage ||
85+
`${site.value.base || ''}images/og-image.png`
86+
})
87+
88+
const canonicalUrl = computed(() => {
89+
const base = site.value.themeConfig?.siteUrl || 'https://docs.halolight.h7ml.cn'
90+
return `${base}${route.path}`
91+
})
92+
93+
const isZhCN = computed(() => {
94+
return !route.path.startsWith('/en/')
95+
})
96+
</script>
97+
98+
<template>
99+
<component :is="'head'">
100+
<!-- Basic Meta Tags -->
101+
<title>{{ fullTitle }}</title>
102+
<meta name="description" :content="pageDescription" />
103+
<meta name="keywords" :content="pageKeywords" />
104+
105+
<!-- Language -->
106+
<meta name="language" :content="isZhCN ? 'zh-CN' : 'en-US'" />
107+
<html :lang="isZhCN ? 'zh-CN' : 'en'" />
108+
109+
<!-- Canonical URL -->
110+
<link rel="canonical" :href="canonicalUrl" />
111+
112+
<!-- Open Graph / Facebook -->
113+
<meta property="og:type" content="website" />
114+
<meta property="og:url" :content="canonicalUrl" />
115+
<meta property="og:title" :content="fullTitle" />
116+
<meta property="og:description" :content="pageDescription" />
117+
<meta property="og:image" :content="ogImage" />
118+
<meta property="og:site_name" content="HaloLight Documentation" />
119+
<meta property="og:locale" :content="isZhCN ? 'zh_CN' : 'en_US'" />
120+
121+
<!-- Twitter Card -->
122+
<meta name="twitter:card" content="summary_large_image" />
123+
<meta name="twitter:url" :content="canonicalUrl" />
124+
<meta name="twitter:title" :content="fullTitle" />
125+
<meta name="twitter:description" :content="pageDescription" />
126+
<meta name="twitter:image" :content="ogImage" />
127+
128+
<!-- Additional SEO -->
129+
<meta name="robots" content="index, follow" />
130+
<meta name="author" content="HaloLight Team" />
131+
<meta name="generator" :content="`VitePress ${site?.value?.version || ''}`" />
132+
133+
<!-- Mobile -->
134+
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5.0" />
135+
<meta name="theme-color" content="#646cff" />
136+
137+
<!-- Favicon -->
138+
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
139+
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
140+
</component>
141+
</template>

‎.vitepress/sidebar.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,7 @@ const enDevelopmentSidebar: DefaultTheme.SidebarItem[] = [
171171
collapsed: false,
172172
items: [
173173
{ text: '📋 Overview', link: '/en/development/' },
174-
{ text: '🌐 Ecosystem', link: '/development/ecosystem' },
174+
{ text: '🌐 Ecosystem', link: '/en/development/ecosystem' },
175175
{ text: '🏗️ Architecture', link: '/en/development/architecture' },
176176
{ text: '🧩 Components', link: '/en/development/components' },
177177
{ text: '📦 State Management', link: '/en/development/state-management' },

‎.vitepress/theme/index.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ import NotFound from './NotFound.vue'
99
import Footer from './Footer.vue'
1010
import Comment from './Comment.vue'
1111
import BackToTop from './BackToTop.vue'
12-
import Announcement from './Announcement.vue'
12+
import SeoMeta from '../components/SeoMeta.vue'
13+
// import Announcement from './Announcement.vue'
1314
import { AiChat } from './ai-chat'
1415
import './custom.css'
1516

@@ -18,10 +19,11 @@ export default {
1819
Layout: () => {
1920
return h(DefaultTheme.Layout, null, {
2021
'not-found': () => h(NotFound),
21-
'layout-top': () => h(Announcement),
22+
// 'layout-top': () => h(Announcement),
2223
'layout-bottom': () => [h(Footer), h(AiChat)],
2324
'doc-after': () => h(Comment),
2425
'aside-outline-after': () => h(BackToTop),
26+
'doc-before': () => h(SeoMeta), // SEO Meta 标签
2527
})
2628
},
2729
enhanceApp({ app }) {

‎README.en.md‎

Lines changed: 47 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -23,36 +23,48 @@ Specification updates land here first, then sync to corresponding implementation
2323

2424
HaloLight is an enterprise-grade admin dashboard solution with multi-framework implementations. Reference implementations:
2525

26-
- Next.js 14 - [Preview](https://halolight.h7ml.cn/) - [GitHub](https://github.com/halolight/halolight)
27-
- Vue 3.5 - [Preview](https://halolight-vue.h7ml.cn/) - [GitHub](https://github.com/halolight/halolight-vue)
26+
- Next.js 14 ✅ · [Preview](https://halolight.h7ml.cn/) · [GitHub](https://github.com/halolight/halolight)
27+
- Vue 3.5 ✅ · [Preview](https://halolight-vue.h7ml.cn/) · [GitHub](https://github.com/halolight/halolight-vue)
2828

29-
Other frameworks (Angular, Nuxt, SvelteKit, Astro, Solid, Qwik, Remix, Preact, Lit, Fresh) are all implemented and deployed. See each repo's README for preview URLs.
29+
All 14 frontend frameworks, 7 backend APIs, and 8 deployment solutions have been implemented and deployed. See each repo's README for preview URLs.
3030

31-
### Framework Versions
31+
### Frontend Frameworks
3232

3333
| Framework | Status | Preview | Repo | Docs |
3434
|-----------|--------|---------|------|------|
35-
| Next.js 14 | Deployed | [Preview](https://halolight.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight) | [Guide](https://halolight.docs.h7ml.cn/en/guide/nextjs) |
36-
| Vue 3.5 | Deployed | [Preview](https://halolight-vue.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-vue) | [Guide](https://halolight.docs.h7ml.cn/en/guide/vue) |
37-
| Angular 21 | Deployed | [Preview](https://halolight-angular.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-angular) | [Guide](https://halolight.docs.h7ml.cn/en/guide/angular) |
38-
| Nuxt 4 | Deployed | [Preview](https://halolight-nuxt.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-nuxt) | [Guide](https://halolight.docs.h7ml.cn/en/guide/nuxt) |
39-
| SvelteKit 2 | Deployed | [Preview](https://halolight-svelte.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-svelte) | [Guide](https://halolight.docs.h7ml.cn/en/guide/sveltekit) |
40-
| Astro 5 | Deployed | [Preview](https://halolight-astro.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-astro) | [Guide](https://halolight.docs.h7ml.cn/en/guide/astro) |
41-
| Solid.js | Deployed | [Preview](https://halolight-solid.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-solid) | [Guide](https://halolight.docs.h7ml.cn/en/guide/solidjs) |
42-
| Qwik | Deployed | [Preview](https://halolight-qwik.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-qwik) | [Guide](https://halolight.docs.h7ml.cn/en/guide/qwik) |
43-
| Remix | Deployed | [Preview](https://halolight-remix.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-remix) | [Guide](https://halolight.docs.h7ml.cn/en/guide/remix) |
44-
| Preact | Deployed | [Preview](https://halolight-preact.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-preact) | [Guide](https://halolight.docs.h7ml.cn/en/guide/preact) |
45-
| Lit | Deployed | [Preview](https://halolight-lit.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-lit) | [Guide](https://halolight.docs.h7ml.cn/en/guide/lit) |
46-
| Fresh (Deno) | Archived | [Preview](https://halolight-fresh.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-fresh) | [Guide](https://halolight.docs.h7ml.cn/en/guide/fresh) |
47-
48-
### Backend Services
49-
50-
| Service | Status | Preview | Repo | Docs |
51-
|---------|--------|---------|------|------|
52-
| Deno + Hono | Deployed | [Preview](https://halolight-deno.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-deno) | [Guide](https://halolight.docs.h7ml.cn/en/guide/deno) |
53-
| Go API | Deployed | [Preview](https://halolight-api-go.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-api-go) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-go) |
54-
| Node.js API | Deployed | [Preview](https://halolight-api-node.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-api-node) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-node) |
55-
| Admin Panel | Private | [Preview](https://halolight-admin.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-admin) | [Guide](https://halolight.docs.h7ml.cn/en/guide/admin) |
35+
| 🟦 Next.js 14 | ✅ Deployed | [Preview](https://halolight.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight) | [Guide](https://halolight.docs.h7ml.cn/en/guide/nextjs) |
36+
| ⚛️ React (Vite) | ✅ Deployed | [Preview](https://halolight-react.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-react) | [Guide](https://halolight.docs.h7ml.cn/en/guide/react) |
37+
| 💚 Vue 3.5 | ✅ Deployed | [Preview](https://halolight-vue.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-vue) | [Guide](https://halolight.docs.h7ml.cn/en/guide/vue) |
38+
| 🔺 Angular 21 | ✅ Deployed | [Preview](https://halolight-angular.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-angular) | [Guide](https://halolight.docs.h7ml.cn/en/guide/angular) |
39+
| 🌿 Nuxt 4 | ✅ Deployed | [Preview](https://halolight-nuxt.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-nuxt) | [Guide](https://halolight.docs.h7ml.cn/en/guide/nuxt) |
40+
| 🧡 SvelteKit 2 | ✅ Deployed | [Preview](https://halolight-svelte.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-svelte) | [Guide](https://halolight.docs.h7ml.cn/en/guide/sveltekit) |
41+
| 🪐 Astro 5 | ✅ Deployed | [Preview](https://halolight-astro.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-astro) | [Guide](https://halolight.docs.h7ml.cn/en/guide/astro) |
42+
| 💠 Solid.js | ✅ Deployed | [Preview](https://halolight-solid.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-solid) | [Guide](https://halolight.docs.h7ml.cn/en/guide/solidjs) |
43+
| ⚡ Qwik | ✅ Deployed | [Preview](https://halolight-qwik.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-qwik) | [Guide](https://halolight.docs.h7ml.cn/en/guide/qwik) |
44+
| 🎸 Remix | ✅ Deployed | [Preview](https://halolight-remix.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-remix) | [Guide](https://halolight.docs.h7ml.cn/en/guide/remix) |
45+
| 🪶 Preact | ✅ Deployed | [Preview](https://halolight-preact.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-preact) | [Guide](https://halolight.docs.h7ml.cn/en/guide/preact) |
46+
| 🔥 Lit | ✅ Deployed | [Preview](https://halolight-lit.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-lit) | [Guide](https://halolight.docs.h7ml.cn/en/guide/lit) |
47+
| 🦖 Fresh (Deno) | ✅ Deployed | [Preview](https://halolight-fresh.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-fresh) | [Guide](https://halolight.docs.h7ml.cn/en/guide/fresh) |
48+
| 🦕 Deno | ✅ Deployed | [Preview](https://halolight-deno.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-deno) | [Guide](https://halolight.docs.h7ml.cn/en/guide/deno) |
49+
50+
### Backend APIs
51+
52+
| Backend Tech | Status | Preview | Repo | Docs |
53+
|--------------|--------|---------|------|------|
54+
| 🦜 NestJS 11 | ✅ Deployed | [API Docs](http://halolight-api-nestjs.h7ml.cn/docs) | [GitHub](https://github.com/halolight/halolight-api-nestjs) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-nestjs) |
55+
| 🐍 Python FastAPI | ✅ Deployed | [API Docs](http://halolight-api-python.h7ml.cn/docs) | [GitHub](https://github.com/halolight/halolight-api-python) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-python) |
56+
| ☕ Java Spring Boot | ✅ Deployed | [API Docs](http://halolight-api-java.h7ml.cn/swagger-ui.html) | [GitHub](https://github.com/halolight/halolight-api-java) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-java) |
57+
| 🐹 Go Fiber | ✅ Deployed | [API Docs](http://halolight-api-go.h7ml.cn/swagger) | [GitHub](https://github.com/halolight/halolight-api-go) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-go) |
58+
| 🟩 Node.js Express | ✅ Deployed | - | [GitHub](https://github.com/halolight/halolight-api-node) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-node) |
59+
| 🐘 PHP Laravel | ✅ Deployed | - | [GitHub](https://github.com/halolight/halolight-api-php) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-php) |
60+
| 🍞 Bun + Hono | ✅ Deployed | - | [GitHub](https://github.com/halolight/halolight-api-bun) | [Guide](https://halolight.docs.h7ml.cn/en/guide/api-bun) |
61+
62+
### Middleware / Full-stack
63+
64+
| Project | Status | Description | Repo | Docs |
65+
|---------|--------|-------------|------|------|
66+
| 🔗 tRPC BFF | ✅ Deployed | Type-safe API Gateway | [GitHub](https://github.com/halolight/halolight-bff) | [Guide](https://halolight.docs.h7ml.cn/en/guide/bff) |
67+
| ⚡ Next.js Action | ✅ Deployed | Server Actions full-stack | [GitHub](https://github.com/halolight/halolight-action) | [Guide](https://halolight.docs.h7ml.cn/en/guide/action) |
5668

5769
### Deployment Options
5870

@@ -64,8 +76,16 @@ Other frameworks (Angular, Nuxt, SvelteKit, Astro, Solid, Qwik, Remix, Preact, L
6476
| Docker | Deployed | - | [GitHub](https://github.com/halolight/halolight-docker) | [Guide](https://halolight.docs.h7ml.cn/en/guide/docker) |
6577
| Railway | Deployed | [Preview](https://halolight-railway.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-railway) | [Guide](https://halolight.docs.h7ml.cn/en/guide/railway) |
6678
| Fly.io | Deployed | [Preview](https://halolight-fly.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-fly) | [Guide](https://halolight.docs.h7ml.cn/en/guide/fly) |
67-
| Azure | Deployed | [Preview](https://halolight-azure.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-azure) | [Guide](https://halolight.docs.h7ml.cn/en/guide/azure) |
68-
| AWS | Deployed | [Preview](https://halolight-aws.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-aws) | [Guide](https://halolight.docs.h7ml.cn/en/guide/aws) |
79+
| Azure | ✅ Deployed | [Preview](https://halolight-azure.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-azure) | [Guide](https://halolight.docs.h7ml.cn/en/guide/azure) |
80+
| AWS | ✅ Deployed | [Preview](https://halolight-aws.h7ml.cn/) | [GitHub](https://github.com/halolight/halolight-aws) | [Guide](https://halolight.docs.h7ml.cn/en/guide/aws) |
81+
82+
### Extension Projects
83+
84+
| Project | Status | Description | Repo | Docs |
85+
|---------|--------|-------------|------|------|
86+
| 🎨 UI Components | ✅ Deployed | Stencil Web Components | [GitHub](https://github.com/halolight/halolight-ui) | [Guide](https://halolight.docs.h7ml.cn/en/guide/ui) |
87+
| 🤖 AI Assistant | 🚧 In Development | RAG + Action Execution | [GitHub](https://github.com/halolight/halolight-ai) | [Guide](https://halolight.docs.h7ml.cn/en/guide/ai) |
88+
| ₿ Web3 Integration | 🚧 In Development | Wallet Login + On-chain Data | [GitHub](https://github.com/halolight/halolight-web3) | [Guide](https://halolight.docs.h7ml.cn/en/guide/web3) |
6989

7090
## Core Features
7191

0 commit comments

Comments
 (0)