Skip to content

Commit 33675e3

Browse files
phantom5099phantom5099
authored
Merge pull request #468 from Yumiue/codex/docs-mcp-skills
docs(www): 重构文档站并补齐 MCP 与 Skills 指南
2 parents 26b3406 + f939b4f commit 33675e3

47 files changed

Lines changed: 3158 additions & 2027 deletions

Some content is hidden

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

‎www/.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
1-
1+
# VitePress build artifacts
2+
cache/
3+
dist/
4+
node_modules/

‎www/.vitepress/config.mts‎

Lines changed: 86 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,19 @@
11
import { defineConfig } from "vitepress";
22

3-
// --- 环境变量检测逻辑 ---
43
const isVercel = process.env.VERCEL === "1";
5-
const isCFPages = process.env.CF_PAGES === "1";
6-
4+
const isCFPages = process.env.CF_PAGES === "1";
75
const isRootDeploy = isVercel || isCFPages;
86

97
const repoUrl = "https://github.com/1024XEngineer/neo-code";
10-
const docsBase = `${repoUrl}/blob/main/docs`;
11-
12-
// 核心修改 1：动态基础路径
138
const base = isRootDeploy ? "/" : "/neo-code/";
149

15-
// 👇👇👇 新增这段调试日志 👇👇👇
16-
console.log("====== VitePress Build Info ======");
17-
console.log("VERCEL Env:", process.env.VERCEL);
18-
console.log("CF_PAGES Env:", process.env.CF_PAGES);
19-
console.log("Final Base Path:", base);
20-
console.log("==================================");
21-
22-
// 核心修改 2：动态站点 URL
2310
let siteUrl = "https://1024xengineer.github.io/neo-code/";
2411
if (isVercel) {
25-
siteUrl = `https://${process.env.VERCEL_URL || 'neocode-docs.vercel.app'}/`;
12+
siteUrl = `https://${process.env.VERCEL_URL || "neocode-docs.vercel.app"}/`;
2613
} else if (isCFPages) {
27-
siteUrl = "https://neocode-docs.pages.dev/";
14+
siteUrl = "https://neocode-docs.pages.dev/";
2815
}
2916

30-
const brandImageUrl = `${siteUrl}brand/neocode-mark.png`;
31-
3217
export default defineConfig({
3318
title: "NeoCode",
3419
description: "基于 Go + Bubble Tea 的本地 Coding Agent 用户指南",
@@ -40,23 +25,26 @@ export default defineConfig({
4025
cleanUrls: true,
4126
lastUpdated: true,
4227
head: [
43-
["meta", { name: "theme-color", content: "#090B1A" }],
44-
["meta", { property: "og:title", content: "NeoCode 用户指南" }],
28+
["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],
29+
["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }],
4530
[
46-
"meta",
31+
"link",
4732
{
48-
property: "og:description",
49-
content: "围绕真实命令、配置与 Gateway 使用场景整理的 NeoCode 用户指导网站。",
33+
rel: "stylesheet",
34+
href: "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600;700&display=swap",
5035
},
5136
],
52-
["meta", { property: "og:type", content: "website" }],
37+
["meta", { name: "theme-color", content: "#f7f7f4" }],
38+
["meta", { property: "og:title", content: "NeoCode 用户指南" }],
5339
[
5440
"meta",
5541
{
56-
property: "og:image",
57-
content: brandImageUrl,
42+
property: "og:description",
43+
content: "围绕真实命令、配置与 Gateway 使用场景整理的 NeoCode 用户指导网站。",
5844
},
5945
],
46+
["meta", { property: "og:type", content: "website" }],
47+
["meta", { property: "og:image", content: `${base}brand/neocode-mark.png` }],
6048
["meta", { name: "twitter:card", content: "summary" }],
6149
// Favicon 路径随 base 变化
6250
["link", { rel: "icon", href: `${base}brand/neocode-mark.png` }],
@@ -81,62 +69,63 @@ export default defineConfig({
8169
link: "/",
8270
themeConfig: {
8371
nav: [
84-
{ text: "开始使用", link: "/guide/" },
85-
{ text: "配置", link: "/guide/configuration" },
86-
{ text: "命令与会话", link: "/guide/quick-start" },
72+
{ text: "快速开始", link: "/guide/" },
73+
{ text: "日常使用", link: "/guide/daily-use" },
74+
{ text: "排障", link: "/guide/troubleshooting" },
8775
{ text: "Gateway", link: "/guide/gateway" },
88-
{ text: "深入阅读", link: "/reference/" },
76+
{ text: "进阶与设计", link: "/reference/" },
8977
{ text: "GitHub", link: repoUrl },
9078
],
9179
sidebar: {
9280
"/guide/": [
9381
{
94-
text: "开始使用",
82+
text: "快速开始",
9583
items: [
9684
{ text: "总览", link: "/guide/" },
97-
{ text: "NeoCode 是什么", link: "/guide/getting-started" },
98-
{ text: "安装与运行", link: "/guide/install" },
99-
{ text: "首次上手", link: "/guide/quick-start" },
85+
{ text: "安装与首次运行", link: "/guide/install" },
86+
{ text: "使用示例", link: "/guide/examples" },
10087
],
10188
},
10289
{
10390
text: "日常使用",
10491
items: [
105-
{ text: "配置入口", link: "/guide/configuration" },
106-
{ text: "工作区与会话", link: "/guide/workspace-session" },
107-
{ text: "记忆与 Skills", link: "/guide/memo-skills" },
108-
{ text: "Gateway 与 URL Dispatch", link: "/guide/gateway" },
109-
{ text: "升级与版本检查", link: "/guide/update" },
92+
{ text: "日常使用", link: "/guide/daily-use" },
93+
{ text: "配置指南", link: "/guide/configuration" },
94+
{ text: "工具与权限", link: "/guide/tools-permissions" },
11095
],
11196
},
112-
],
113-
"/reference/": [
11497
{
115-
text: "深入阅读",
98+
text: "扩展能力",
11699
items: [
117-
{ text: "文档导航", link: "/reference/" },
118-
{ text: "旧入口兼容页", link: "/docs/" },
100+
{ text: "MCP 工具接入", link: "/guide/mcp" },
101+
{ text: "Skills 使用", link: "/guide/skills" },
102+
],
103+
},
104+
{
105+
text: "质量与协作",
106+
items: [
107+
{ text: "排障与常见问题", link: "/guide/troubleshooting" },
108+
{ text: "Gateway 使用", link: "/guide/gateway" },
109+
{ text: "升级与版本检查", link: "/guide/update" },
119110
],
120111
},
121112
],
122-
"/docs/": [
113+
"/reference/": [
123114
{
124-
text: "文档入口",
115+
text: "深入阅读",
125116
items: [
126-
{ text: "总览", link: "/docs/" },
127-
{ text: "开始使用", link: "/guide/" },
128-
{ text: "深入阅读", link: "/reference/" },
117+
{ text: "文档导航", link: "/reference/" },
129118
],
130119
},
131120
],
132121
"/": [
133122
{
134123
text: "快速导航",
135124
items: [
136-
{ text: "开始使用", link: "/guide/" },
137-
{ text: "安装与运行", link: "/guide/install" },
138-
{ text: "首次上手", link: "/guide/quick-start" },
139-
{ text: "配置入口", link: "/guide/configuration" },
125+
{ text: "快速开始", link: "/guide/" },
126+
{ text: "安装与首次运行", link: "/guide/install" },
127+
{ text: "日常使用", link: "/guide/daily-use" },
128+
{ text: "排障", link: "/guide/troubleshooting" },
140129
],
141130
},
142131
],
@@ -169,18 +158,54 @@ export default defineConfig({
169158
"A compact NeoCode docs entrypoint focused on current, verifiable behavior.",
170159
themeConfig: {
171160
nav: [
172-
{ text: "Home", link: "/en/" },
173-
{ text: "Docs", link: "/en/docs/" },
161+
{ text: "Getting Started", link: "/en/guide/" },
162+
{ text: "Daily Use", link: "/en/guide/daily-use" },
163+
{ text: "Troubleshooting", link: "/en/guide/troubleshooting" },
164+
// Gateway 页面仅有中文版，英文站跨语言指向
165+
{ text: "Gateway", link: "/guide/gateway" },
166+
{ text: "Reference", link: "/reference/" },
174167
{ text: "GitHub", link: repoUrl },
175168
],
176169
sidebar: {
177-
"/en/docs/": [
170+
"/en/guide/": [
171+
{
172+
text: "Getting Started",
173+
items: [
174+
{ text: "Getting Started", link: "/en/guide/" },
175+
{ text: "Install & First Run", link: "/en/guide/install" },
176+
{ text: "Usage Examples", link: "/en/guide/examples" },
177+
],
178+
},
179+
{
180+
text: "Daily Use",
181+
items: [
182+
{ text: "Daily Use", link: "/en/guide/daily-use" },
183+
{ text: "Configuration", link: "/en/guide/configuration" },
184+
{ text: "Tools & Permissions", link: "/en/guide/tools-permissions" },
185+
],
186+
},
187+
{
188+
text: "Extensions",
189+
items: [
190+
{ text: "MCP Tools", link: "/en/guide/mcp" },
191+
{ text: "Skills", link: "/en/guide/skills" },
192+
],
193+
},
194+
{
195+
text: "Quality & Ops",
196+
items: [
197+
{ text: "Troubleshooting", link: "/en/guide/troubleshooting" },
198+
// Gateway 页面仅有中文版，英文站跨语言指向
199+
{ text: "Gateway Usage", link: "/guide/gateway" },
200+
{ text: "Update & Version", link: "/en/guide/update" },
201+
],
202+
},
203+
],
204+
"/reference/": [
178205
{
179-
text: "Overview",
206+
text: "Reference",
180207
items: [
181-
{ text: "Docs Index", link: "/en/docs/" },
182-
{ text: "Chinese Guide", link: "/guide/" },
183-
{ text: "Architecture Notes", link: "/reference/" },
208+
{ text: "Documentation Index", link: "/reference/" },
184209
],
185210
},
186211
],
@@ -210,9 +235,5 @@ export default defineConfig({
210235
sitemap: {
211236
hostname: siteUrl,
212237
},
213-
vite: {
214-
define: {
215-
__NEOCODE_DOCS_BASE__: JSON.stringify(docsBase),
216-
},
217-
},
238+
218239
});

‎www/.vitepress/theme/components/HomeLanding.vue‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<script setup lang="ts">
2+
import { computed } from 'vue'
3+
import { withBase } from 'vitepress'
4+
5+
const props = defineProps<{
6+
locale?: 'zh' | 'en'
7+
}>()
8+
9+
type LinkItem = {
10+
text: string
11+
href: string
12+
external?: boolean
13+
variant?: 'primary' | 'secondary'
14+
}
15+
16+
type ValueItem = {
17+
title: string
18+
description: string
19+
}
20+
21+
type LandingContent = {
22+
eyebrow: string
23+
title: string
24+
description: string
25+
actions: LinkItem[]
26+
values: ValueItem[]
27+
}
28+
29+
const contents: Record<'zh' | 'en', LandingContent> = {
30+
zh: {
31+
eyebrow: 'NeoCode Coding Agent',
32+
title: '终端里的本地 AI 编码助手',
33+
description:
34+
'本地运行，贴合终端工作流。从理解代码、修改文件到运行验证，NeoCode 帮你把一次代码任务完整推进。',
35+
actions: [
36+
{ text: '立即安装', href: '/guide/install', variant: 'primary' },
37+
{ text: '查看示例', href: '/guide/examples', variant: 'secondary' },
38+
{ text: 'GitHub', href: 'https://github.com/1024XEngineer/neo-code', external: true, variant: 'secondary' },
39+
],
40+
values: [
41+
{ title: '本地运行', description: '配置和工作区留在你的机器上。' },
42+
{ title: '终端原生', description: '直接融入 shell 和 TUI 工作流。' },
43+
{ title: '工具可控', description: '写文件、跑命令前保留确认边界。' },
44+
],
45+
},
46+
en: {
47+
eyebrow: 'NeoCode Coding Agent',
48+
title: 'A local AI coding agent for your terminal',
49+
description:
50+
'Run locally, stay in your terminal workflow, and move a code task from understanding to edits and verification.',
51+
actions: [
52+
{ text: 'Install now', href: '/en/guide/install', variant: 'primary' },
53+
{ text: 'See examples', href: '/en/guide/examples', variant: 'secondary' },
54+
{ text: 'GitHub', href: 'https://github.com/1024XEngineer/neo-code', external: true, variant: 'secondary' },
55+
],
56+
values: [
57+
{ title: 'Local first', description: 'Config and workspace stay on your machine.' },
58+
{ title: 'Terminal native', description: 'Designed for shell and TUI workflows.' },
59+
{ title: 'Controlled tools', description: 'File edits and commands keep approval boundaries.' },
60+
],
61+
},
62+
}
63+
64+
const currentLocale = computed<'zh' | 'en'>(() => (props.locale === 'en' ? 'en' : 'zh'))
65+
const content = computed(() => contents[currentLocale.value])
66+
67+
// hrefFor 负责统一处理站内链接的 base 前缀，同时保留外部链接原始地址。
68+
function hrefFor(item: LinkItem) {
69+
if (item.external) {
70+
return item.href
71+
}
72+
return withBase(item.href)
73+
}
74+
</script>
75+
76+
<template>
77+
<div class="home-landing">
78+
<section class="home-hero" aria-labelledby="home-title">
79+
<p class="home-eyebrow">{{ content.eyebrow }}</p>
80+
<h1 id="home-title">{{ content.title }}</h1>
81+
<p class="home-hero__lead">{{ content.description }}</p>
82+
83+
<div class="home-actions">
84+
<a
85+
v-for="action in content.actions"
86+
:key="action.text"
87+
class="home-action"
88+
:class="`home-action--${action.variant || 'secondary'}`"
89+
:href="hrefFor(action)"
90+
:target="action.external ? '_blank' : undefined"
91+
:rel="action.external ? 'noreferrer' : undefined"
92+
>
93+
{{ action.text }}
94+
</a>
95+
</div>
96+
97+
<div class="home-values" aria-label="NeoCode highlights">
98+
<div v-for="value in content.values" :key="value.title" class="home-value">
99+
<strong>{{ value.title }}</strong>
100+
<span>{{ value.description }}</span>
101+
</div>
102+
</div>
103+
</section>
104+
</div>
105+
</template>

0 commit comments

Comments
 (0)