VitePress 使用指南

本项目使用 VitePress 构建技术文档站点，本指南介绍如何添加新文档和管理路由。

项目结构

docs/
├── .vitepress/
│   ├── config.mts          # VitePress 配置文件
│   └── utils/
│       └── sidebar.ts      # 侧边栏生成工具（可选）
├── clean-code/             # 代码整洁之道
│   ├── index.md           # 目录首页
│   └── solid.md           # SOLID 原则
├── frontend/               # 前端技术
│   ├── index.md           # 目录首页
│   ├── vue-best-practices.md
│   └── typescript-guide.md
├── index.md               # 网站首页
└── vitepress-guide.md     # VitePress 使用指南

路由规则

VitePress 使用基于文件的路由系统：

1. 自动路由映射

• docs/index.md → /
• docs/clean-code/index.md → /clean-code
• docs/clean-code/solid.md → /clean-code/solid
• docs/frontend/vue-best-practices.md → /frontend/vue-best-practices

2. 目录索引页

每个目录都应该有一个 index.md 文件作为该目录的首页：

# 目录名称

> 简短描述

## 概述
目录内容的概述...

## 文章列表
- [文章1](./article1.md)
- [文章2](./article2.md)

添加新文档

1. 创建新的技术分类

1. 在 docs/ 下创建新目录，如 backend/
2. 创建 docs/backend/index.md 作为首页
3. 在 docs/.vitepress/config.mts 中添加导航和侧边栏配置

// 在 nav 中添加
{ text: '后端技术', link: '/backend/' }

// 在 sidebar 中添加
'/backend/': [
  {
    text: '后端技术',
    items: [
      { text: '概述', link: '/backend/' },
      // 其他文章...
    ]
  }
]

4. 更新首页 docs/index.md 的 features 部分

2. 在现有分类下添加文章

1. 在对应目录下创建 .md 文件
2. 在 docs/.vitepress/config.mts 的对应侧边栏中添加链接
3. 在目录的 index.md 中添加文章链接

配置说明

主配置文件 config.mts

export default defineConfig({
  title: "易墨的技术笔记",
  description: "记录技术成长路径，分享编程实践经验",
  
  themeConfig: {
    // 顶部导航
    nav: [
      { text: '首页', link: '/' },
      { text: '代码整洁之道', link: '/clean-code/' },
      // ...
    ],

    // 侧边栏配置
    sidebar: {
      '/clean-code/': [
        {
          text: '代码整洁之道',
          items: [
            { text: '概述', link: '/clean-code/' },
            { text: 'SOLID 五大原则', link: '/clean-code/solid' }
          ]
        }
      ],
      // ...
    }
  }
})

首页配置 index.md

---
layout: home

hero:
  name: "易墨的技术笔记"
  text: "记录技术成长路径"
  tagline: 分享编程实践经验，探索技术深度与广度
  actions:
    - theme: brand
      text: 开始阅读
      link: /clean-code/

features:
  - title: 🧹 代码整洁之道
    details: 学习编写可读、可维护、可扩展的高质量代码
    link: /clean-code/
---

文档编写规范

1. Front Matter

每个文档可以包含 Front Matter 来配置页面：

---
title: 页面标题
description: 页面描述
---

# 文档标题

2. 标题层级

• 使用 # 作为页面主标题（H1）
• 使用 ## 作为主要章节（H2）
• 使用 ### 作为子章节（H3）

3. 代码块

使用语言标识符来启用语法高亮：

```ts
const message: string = 'Hello VitePress!'

### 4. 链接
- 内部链接：`[文本](./other-page.md)`
- 外部链接：`[文本](https://example.com)`

## 开发命令

```bash
# 启动开发服务器
npm run docs:dev

# 构建生产版本
npm run docs:build

# 预览构建结果
npm run docs:preview

部署

1. 静态部署

构建后的文件在 docs/.vitepress/dist/ 目录，可以部署到任何静态文件服务器。

2. GitHub Pages

在 .github/workflows/deploy.yml 中配置自动部署：

name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run docs:build
      - uses: actions/upload-pages-artifact@v2
        with:
          path: docs/.vitepress/dist

最佳实践

1. 目录结构清晰：按技术领域组织文档
2. 索引页完整：每个目录都有详细的 index.md
3. 链接维护：及时更新内部链接
4. 搜索优化：使用描述性的标题和内容
5. 移动友好：VitePress 默认响应式，注意内容布局

扩展功能

1. 自定义组件

在 .vitepress/theme/ 中可以添加自定义 Vue 组件。

2. 插件集成

可以集成各种 VitePress 插件来扩展功能。

3. 主题定制

通过 CSS 变量或自定义主题来调整样式。

---

通过遵循这些规范，可以构建一个结构清晰、易于维护的技术文档站点。