# xusir的vitepress文档

**Repository Path**: shanjun666/xusirs-vitepress-documentation

## Basic Information

- **Project Name**: xusir的vitepress文档
- **Description**: 基于VitePress的个人文档站点，专注技术分享与知识沉淀，简洁高效，开源可定制。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SiteName

> 产品官网 + 文档站 · 基于 **VitePress + Vue 3** 搭建，支持中英双语（i18n）与亮暗双色（light/dark），便于后续扩展。

## 技术栈

- [VitePress](https://vitepress.dev/) 1.x（静态站点生成器，基于 Vite + Vue 3）
- Vue 3（自定义组件 / 交互演示）
- pnpm（包管理）

## 快速开始

```bash
pnpm install        # 安装依赖
pnpm docs:dev       # 本地开发（默认 http://localhost:5173）
pnpm docs:build     # 构建静态站点 → docs/.vitepress/dist
pnpm docs:preview   # 预览构建产物
```

## 目录结构

```
.
├─ docs/                         # 站点源目录
│  ├─ .vitepress/
│  │  ├─ config.ts               # 站点配置：i18n / 导航 / 侧边栏 / 品牌
│  │  └─ theme/
│  │     ├─ index.ts             # 主题入口：注册全局 Vue 组件
│  │     ├─ styles.css           # 品牌色（Stripe 紫）与亮暗变量
│  │     └─ components/
│  │        └─ DemoBox.vue        # 示例全局组件
│  ├─ index.md                   # 中文首页（landing）
│  ├─ guide/                     # 中文文档
│  │  ├─ getting-started.md
│  │  └─ components.md
│  ├─ en/                        # 英文版本
│  │  ├─ index.md
│  │  └─ guide/
│  └─ public/                    # 静态资源（logo 等）
├─ package.json
└─ .gitignore
```

## 关键约定

### 1. 替换品牌名

全文使用占位名 `SiteName`。替换方式：

- 修改 `docs/.vitepress/config.ts` 顶部的 `const BRAND = 'SiteName'`；
- 全局搜索并替换各 Markdown 文件中的 `SiteName`。

### 2. 中英双语（i18n）

- 默认语言为**中文**，根路径 `/` 即中文；
- 英文位于 `/en/`，导航栏可切换；
- 新增页面时，中文放 `docs/`，英文放 `docs/en/` 对应路径，并在 `config.ts` 的 `locales` 中同步维护 `nav` / `sidebar`。

### 3. 亮暗双色

- 已在 `config.ts` 设置 `appearance: true`，导航栏自带主题切换；
- 品牌色在 `docs/.vitepress/theme/styles.css` 中覆写，亮暗各一套变量（Stripe 紫 `#635BFF`）。

### 4. 扩展自定义 Vue 组件

1. 在 `docs/.vitepress/theme/components/` 新建 `.vue`；
2. 在 `docs/.vitepress/theme/index.ts` 用 `app.component('Name', Comp)` 注册；
3. 在任意 Markdown 中写 `<Name />` 即可。
   （已内置示例 `DemoBox`，见首页与 `/guide/components`。）

## 部署

当前仅配置了本地 `dev/build/preview`。如需上线，可后续接入 GitHub Pages 或 CloudStudio 静态托管（在 `docs:build` 产物 `docs/.vitepress/dist` 基础上配置 CI 即可）。