VitePress 搭建与汉化实施指南

项目目标: 构建一个高性能、极简风格的个人知识库站点，支持全文搜索和中文导航。 参考模版: Neat 项目 (neat/clients/docs)

1. 环境初始化 (Initialization)

1.1 基础安装

在根目录 c:\Users\hongj\source\wiki\full-stack 下执行：

# 1. 初始化 package.json
npm init -y

# 2. 安装 VitePress 和 Vue
npm install -D vitepress vue

# 3. 配置 .gitignore
echo "node_modules" >> .gitignore
echo ".vitepress/dist" >> .gitignore
echo ".vitepress/cache" >> .gitignore

1.2 目录结构配置

建议将配置集中在 .vitepress 目录，保持根目录整洁：

/full-stack
├── .vitepress/
│   ├── config.mjs       # 核心配置文件
│   ├── theme/           # 自定义主题
│   │   ├── index.js
│   │   └── style.css
├── knowledge/           # 文档内容源
├── index.md             # 站点首页
└── package.json

2. 核心配置与迁移 (Configuration)

2.1 配置文件迁移

从 Neat 项目复制配置并进行适配：

1. Theme 迁移: 复制 style.css (极简黑白风格) 和 index.js 到 .vitepress/theme。
2. Config 调整 (config.mjs):
   • Sidebar: 修改 getSidebarItems 逻辑，使其支持递归扫描 knowledge 下的多级目录（00-Core, 01-Stack 等）。
   • Search: 启用本地全文搜索 (provider: 'local')。

2.2 导航汉化 (Localization)

为了提升阅读体验，需将侧边栏和顶部导航的英文目录名映射为中文。

顶部导航 (Nav) 映射:

nav: [
  { text: '核心架构', link: '/knowledge/00-core/', activeMatch: '/knowledge/00-core/' },
  { text: '技术栈', link: '/knowledge/01-stack/', activeMatch: '/knowledge/01-stack/' },
  { text: '工具箱', link: '/knowledge/02-toolkit/', activeMatch: '/knowledge/02-toolkit/' },
  { text: '工程化', link: '/knowledge/03-engineering/', activeMatch: '/knowledge/03-engineering/' }
]

侧边栏 (Sidebar) 汉化: VitePress 侧边栏标题默认读取目录下的 index.md 的 title 字段。因此，需为关键目录创建或更新 index.md：

目录 (kebab-case)	Front Matter Title
architecture	架构设计
backend	后端技术
frontend	前端开发
devops	运维部署
database	数据库

3. 文档标准化 (Standardization)

为了支持自动化侧边栏和汉化，所有 Markdown 文档必须包含标准的 Front Matter。

3.1 标准化脚本

使用 normalize_frontmatter.py 脚本批量处理：

1. 提取标题: 优先取 title 字段 -> 正文 H1 -> 文件名。
2. 补全字段: 确保包含 title, order (默认 100), lastUpdated: true。
3. 保留术语: 对 .NET, Docker 等专有名词保留英文原名。

4. 首页重构 (Homepage Refactoring)

修改根目录下的 index.md，对标 Neat 风格：

---
layout: home

hero:
  name: "Ark Knowledge Base"
  text: "构建结构化的第二大脑"
  tagline: "Architecture · Full Stack · Engineering"
  actions:
    - theme: brand
      text: 浏览知识库
      link: /knowledge/00-core/
    - theme: alt
      text: GitHub
      link: https://github.com/your-repo

features:
  - title: 核心架构
    details: 设计模式、分布式系统与计算机科学基础。
    link: /knowledge/00-core/
  - title: 全栈技术
    details: .NET, Python, Vue, Database 深度沉淀。
    link: /knowledge/01-stack/
  - title: 工程实践
    details: 规范、测试、CI/CD 与项目管理方法论。
    link: /knowledge/03-engineering/
---

5. 部署与预览

配置 package.json 脚本：

"scripts": {
  "docs:dev": "vitepress dev",
  "docs:build": "vitepress build",
  "docs:preview": "vitepress preview"
}

运行 npm run docs:dev 启动本地服务进行验证。