docs

Instruction file imported from wuxingxi888/vite-vue3-h5-template (.cursor/rules/docs.mdc). Copyright stays with the author.

项目描述

该项目是一个基于 VitePress 构建的技术文档站点，用于记录和展示 vite-vue3-h5-template 项目的使用说明、技术细节和最佳实践。

项目目录结构说明

1. apps/docs 为文档项目根目录
2. apps/docs/.vitepress 为 VitePress 配置目录
3. apps/docs/.vitepress/config.ts 为 VitePress 主配置文件
4. apps/docs/.vitepress/nav 为导航栏配置目录
5. apps/docs/.vitepress/menu 为侧边栏配置目录
6. apps/docs/guide 为主要文档内容目录
7. apps/docs/public 为静态资源目录

开发规范

1. 目录命名：目录与文件一律使用小驼峰（camelCase），但文档文件使用 kebab-case（短横线分隔）命名。
2. 文档结构：
   • 每个文档文件开头必须包含标题（# 标题）
   • 文档内容应结构清晰，使用适当的标题层级（##、### 等）
   • 代码块应标明语言类型（如 ts、bash）
3. 目录出口文件：
   • 每个配置目录下必须保留 index.ts 或 index.js 作为统一出口，仅做导出聚合；不得包含业务逻辑。
   • 禁止在聚合文件中导出外部依赖或上层模块。
4. 导航配置：
   • 导航配置位于 apps/docs/.vitepress/nav 目录
   • 主配置文件为 apps/docs/.vitepress/nav/index.ts
   • 导航项应清晰分类，重要链接放在前面
5. 侧边栏配置：
   • 侧边栏配置位于 apps/docs/.vitepress/menu 目录
   • 主配置文件为 apps/docs/.vitepress/menu/index.js
   • 每个模块应有独立配置文件，通过主配置文件聚合
6. 文档内容组织：
   • guide 目录为主要文档内容目录
   • 按功能模块创建子目录组织文档
   • 每个子目录应有 index.md 作为入口文件
7. 链接规范：
   • 内部链接使用相对路径
   • 外部链接应明确标注目标地址
   • 图片资源放置在 public 目录下，使用绝对路径引用
8. 导入路径：
   • 统一使用相对路径进行模块导入
   • 避免循环依赖
9. 类型导入：
   • TypeScript 类型使用 import type 单独导入
   • 禁止将类型与值混在同一 import 语句中

文档编写规范

1. 标题规范：
   • 文档主标题使用一级标题（#）
   • 章节标题使用二级标题（##）
   • 子章节使用三级标题（###）
   • 依次类推，最多使用六级标题
2. 代码示例：
   • 所有代码块必须指定语言类型
   • 配置代码示例应简洁明了，突出重点
   • 长代码应添加必要的注释说明
3. 列表规范：
   • 无序列表使用短横线（-）标记
   • 有序列表使用数字加点标记
   • 嵌套列表应保持一致的缩进
4. 链接规范：
   • 内部文档链接使用相对路径，以 .md 结尾
   • 外部链接使用完整 URL
   • 重要链接应添加描述性文字
5. 强调规范：
   • 重要信息使用加粗（文本）
   • 代码、命令使用行内代码（code）
   • 文件路径、命令使用行内代码标记

组件与配置设计规范

1. 导航配置：
   • 导航项应简洁明了，避免过长文本
   • 下拉菜单项应按逻辑分组
   • 重要链接应放在显眼位置
2. 侧边栏配置：
   • 侧边栏应按功能模块组织
   • 支持折叠的模块应设置 collapsible 属性
   • 默认展开重要的内容模块
3. 配置项：
   • 配置项应有详细注释说明
   • 复杂配置应拆分为多个子配置
   • 配置项的类型应明确指定

强制要求

1. 在生成文档时，优先生成完整示例；确保文档内容准确、完整。
2. 统一使用相对路径引用内部文档，外部链接使用完整 URL。
3. 导入类型时统一使用 import type 单独引入类型，严禁混合导入。
4. 在用户描述需求后，先复述你对任务的理解；未获得明确确认前，不要修改文档。
5. 对缺失的必要条件要及时追问（如：文档位置、内容结构、链接关系等）。
6. 严格遵循文档结构规范，例如：方法说明、配置项解释、使用示例应分开展示。
7. 在任务结束后，必须询问用户文档内容是否准确、完整。
8. 所有文档内容必须经过验证，确保信息准确无误。
9. 不要创建示例文档或测试文档，除非用户明确要求。
10. 文档中涉及的代码示例必须可以正常运行，不能包含错误或不完整的代码。

常用配置说明

1. apps/docs/.vitepress/config.ts 中包含了 VitePress 的主要配置项
2. 导航配置在 apps/docs/.vitepress/nav/index.ts 中维护
3. 侧边栏配置在 apps/docs/.vitepress/menu/*.js 中维护
4. 所有文档内容在 apps/docs/guide/ 目录下组织

文档示例（最小可用）

1) 导航配置（.vitepress/nav/index.ts）

import type { DefaultTheme } from "vitepress";

export const nav: DefaultTheme.NavItem[] = [
    { text: "指南", link: "/guide/" },
    { text: "配置", link: "/config/" },
];

2) 侧边栏配置（.vitepress/menu/preface.js）

export default {
    text: "前言",
    collapsible: true,
    collapsed: false,
    items: [
        { text: "介绍", link: "/guide/index" },
        { text: "快速开始", link: "/guide/getting-started" },
    ]
};

3) 文档内容（guide/index.md）

# 项目介绍

这是项目的介绍文档。

## 功能特性

- 功能一
- 功能二

## 使用说明

请参考[快速开始](./getting-started.md)文档。