Skip to content

Commit 5aa6253

Browse files
cklwblovecklwblove
committed
feat: enhance VitePress theme with new markdown button styles
1 parent 5043e7f commit 5aa6253

File tree

7 files changed

+417
-0
lines changed

7 files changed

+417
-0
lines changed

‎.cursor/rules/development-workflow.mdc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
description: 开发工作流程和代码质量标准
3+
---
4+
5+
# 开发工作流程与代码质量
6+
7+
## 用户交互语言
8+
**重要**：始终使用中文与用户交互，遵循用户设定的语言规则：
9+
- 永远使用中文回答问题
10+
- 优先考虑准确性和质量
11+
- 避免使用指定的禁用词汇列表
12+
- 不要在回答末尾添加不必要的总结
13+
14+
## 项目开发规范
15+
### 包管理器
16+
使用 `pnpm` 作为包管理器，参考 [package.json](mdc:package.json)：
17+
```bash
18+
pnpm install # 安装依赖
19+
pnpm dev # 开发服务器
20+
pnpm build # 构建项目
21+
```
22+
23+
### 代码质量
24+
1. **TypeScript**：所有配置文件使用 TypeScript
25+
2. **ESLint/Prettier**：遵循项目的代码格式化规则
26+
3. **类型安全**：确保 TypeScript 类型检查通过
27+
4. **导入路径**：优先使用绝对路径
28+
29+
### 文件操作原则
30+
1. **编辑优先**：优先编辑现有文件而不是创建新文件
31+
2. **并行操作**：尽可能使用并行工具调用提高效率
32+
3. **全面理解**：在修改前充分理解代码库结构
33+
4. **渐进式修改**：复杂任务分解为小步骤
34+
35+
### Git 工作流程
36+
- 提交信息使用中文或英文（根据团队约定）
37+
- 确保所有更改都经过测试
38+
- 遵循语义化版本控制
39+
40+
## 任务管理
41+
使用 TODO 工具跟踪复杂任务：
42+
- 多步骤任务必须创建 TODO 列表
43+
- 及时更新任务状态
44+
- 完成后立即标记为完成
45+
46+
## 错误处理
47+
1. **Linter 错误**：修改文件后检查并修复语法错误
48+
2. **构建错误**：确保修改不会破坏现有功能
49+
3. **类型错误**：解决 TypeScript 类型问题
50+
51+
## 文档更新
52+
任何代码更改都应该：
53+
- 更新相关文档
54+
- 保持中英文版本同步
55+
- 验证示例代码的正确性

‎.cursor/rules/git-commit.mdc‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
description: Git 提交规范和最佳实践
3+
---
4+
5+
# Git 提交规范
6+
7+
## 提交信息格式
8+
使用语义化提交信息格式，支持中英文：
9+
10+
```
11+
<类型>(<范围>): <描述>
12+
13+
[可选的正文]
14+
15+
[可选的脚注]
16+
```
17+
18+
### 提交类型 (Type)
19+
| 类型 | 说明 | 示例 |
20+
|------|------|------|
21+
| `feat` | 新功能 | `feat: 添加插件配置说明` |
22+
| `fix` | 修复 | `fix: 修复配置文件类型错误` |
23+
| `docs` | 文档更新 | `docs: 翻译 viewport.md 为英文` |
24+
| `style` | 样式修改 | `style: 更新按钮 hover 样式` |
25+
| `refactor` | 重构 | `refactor: 重构主题样式结构` |
26+
| `i18n` | 国际化 | `i18n: 添加中文配置说明` |
27+
| `config` | 配置修改 | `config: 更新 VitePress 配置` |
28+
| `chore` | 构建/工具 | `chore: 更新依赖版本` |
29+
30+
### 范围 (Scope)
31+
根据修改的文件类型或功能模块：
32+
33+
| 范围 | 说明 | 文件路径示例 |
34+
|------|------|-------------|
35+
| `config` | 配置文件 | [.vitepress/config.ts](mdc:.vitepress/config.ts) |
36+
| `theme` | 主题样式 | [.vitepress/theme/](mdc:.vitepress/theme/) |
37+
| `plugins` | 插件文档 | [src/plugins/](mdc:src/plugins/) |
38+
| `guides` | 指南文档 | [src/guides/](mdc:src/guides/) |
39+
| `api` | API 文档 | [src/api/](mdc:src/api/) |
40+
| `zh` | 中文文档 | [src/zh/](mdc:src/zh/) |
41+
| `en` | 英文文档 | [src/](mdc:src/) |
42+
43+
## 提交示例
44+
45+
### 文档翻译
46+
```bash
47+
# 好的示例
48+
docs(plugins): 翻译 viewport.md 为英文
49+
i18n(guides): 添加快速开始中文版本
50+
51+
# 避免
52+
update viewport
53+
translate file
54+
```
55+
56+
### 样式修改
57+
```bash
58+
# 好的示例
59+
style(theme): 重置 markdown 按钮 hover 颜色
60+
feat(theme): 添加深色模式支持
61+
62+
# 避免
63+
fix css
64+
update styles
65+
```
66+
67+
### 配置更改
68+
```bash
69+
# 好的示例
70+
config(vitepress): 添加 llmstxt 插件配置
71+
fix(config): 修复 TypeScript 类型错误
72+
73+
# 避免
74+
update config
75+
fix error
76+
```
77+
78+
## 提交前检查清单
79+
80+
### 📋 必检项目
81+
- [ ] **文件完整性**：确保所有修改的文件都已暂存
82+
- [ ] **语法检查**：运行 `pnpm lint` 检查代码质量
83+
- [ ] **构建测试**：运行 `pnpm build` 确保构建成功
84+
- [ ] **双语同步**：如修改文档，确保中英文版本保持一致
85+
86+
### 📝 文档类提交
87+
- [ ] **链接有效性**：检查所有内部和外部链接
88+
- [ ] **代码示例**：验证代码示例可以正常运行
89+
- [ ] **格式一致性**：保持 Markdown 格式规范
90+
- [ ] **术语统一**：使用项目术语对照表
91+
92+
### 🎨 样式类提交
93+
- [ ] **响应式测试**：在不同屏幕尺寸下测试
94+
- [ ] **深色模式**：确保深色模式显示正常
95+
- [ ] **浏览器兼容**：在主流浏览器中验证
96+
- [ ] **CSS 变量**：优先使用 VitePress 主题变量
97+
98+
## 提交频率建议
99+
100+
### 🔄 及时提交
101+
- **单一功能**：完成一个功能点立即提交
102+
- **文档翻译**：翻译完一个文件就提交
103+
- **样式调整**：完成一个组件样式修改就提交
104+
- **配置更改**：配置修改并验证后立即提交
105+
106+
### 🚫 避免的提交模式
107+
- **大批量提交**：一次性提交多个不相关的更改
108+
- **模糊描述**：使用 "fix", "update", "change" 等模糊词汇
109+
- **中英文混用**：提交信息语言不一致
110+
- **缺少范围**：没有明确指出修改的范围
111+
112+
## 分支管理
113+
114+
### 主要分支
115+
- **main**：稳定的生产版本
116+
- **develop**：开发分支，功能集成
117+
- **feature/**：功能分支，如 `feature/zh-translation`
118+
- **fix/**：修复分支，如 `fix/config-type-error`
119+
120+
### 合并策略
121+
```bash
122+
# 功能完成后合并到 develop
123+
git checkout develop
124+
git merge --no-ff feature/feature-name
125+
126+
# 发布时合并到 main
127+
git checkout main
128+
git merge --no-ff develop
129+
```
130+
131+
## 工具集成
132+
133+
### 提交模板
134+
可以设置 git 提交模板：
135+
```bash
136+
git config commit.template .gitmessage
137+
```
138+
139+
### 自动化检查
140+
推荐使用 husky + lint-staged 进行提交前自动检查：
141+
- ESLint 代码检查
142+
- Prettier 格式化
143+
- TypeScript 类型检查
144+
- Markdown 链接验证

‎.cursor/rules/markdown-translation.mdc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
globs: *.md
3+
---
4+
5+
# Markdown 文档翻译指南
6+
7+
## 翻译原则
8+
当进行中英文翻译时，请遵循以下规则：
9+
10+
### 术语保持一致
11+
- **WinJS** → 保持不变
12+
- **插件化** → Plugin-based
13+
- **前端应用框架** → Frontend Application Framework
14+
- **配置式路由** → Configured routing
15+
- **约定式路由** → Conventional routing
16+
- **生命周期** → Lifecycle
17+
18+
### 技术术语处理
19+
1. **代码块和配置参数名称**：保持原样，不翻译
20+
2. **URL 和链接**：保持原样
21+
3. **示例代码**：注释可以翻译，代码本身不变
22+
23+
### 文档结构
24+
- 保持原有的 Markdown 格式和层级结构
25+
- 表格结构保持一致
26+
- 代码块的语言标识符保持不变
27+
28+
### 质量要求
29+
1. 保持技术准确性
30+
2. 语言自然流畅
31+
3. 专业术语使用标准译法
32+
4. 避免过度翻译技术名词
33+
34+
## 参考文件
35+
- 已翻译示例：[src/plugins/viewport.md](mdc:src/plugins/viewport.md)
36+
- VitePress 配置：[.vitepress/config.ts](mdc:.vitepress/config.ts)

‎.cursor/rules/plugin-docs.mdc‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
description: 插件文档编写和维护指南
3+
---
4+
5+
# WinJS 插件文档编写指南
6+
7+
## 插件文档结构
8+
所有插件文档位于 [src/plugins/](mdc:src/plugins/) 和 [src/zh/plugins/](mdc:src/zh/plugins/) 目录。
9+
10+
### 标准文档模板
11+
每个插件文档应包含以下部分：
12+
13+
```markdown
14+
# @winner-fed/plugin-name
15+
16+
Brief description in English.
17+
18+
## 安装 (Installation)
19+
\`\`\`bash
20+
npm add @winner-fed/plugin-name -D
21+
\`\`\`
22+
23+
## 使用 (Usage)
24+
配置示例：
25+
\`\`\`ts
26+
// .winrc.ts
27+
export default {
28+
plugins: ['@winner-fed/plugin-name'],
29+
pluginName: {
30+
// 配置选项
31+
}
32+
};
33+
\`\`\`
34+
35+
## 配置选项 (Options)
36+
| Name | Type | Default | Description |
37+
|------|------|---------|-------------|
38+
39+
## 示例 (Examples)
40+
实际使用案例和代码示例
41+
```
42+
43+
### 文档维护要求
44+
1. **双语同步**：英文和中文版本内容保持一致
45+
2. **API 文档**：所有配置参数必须有详细说明
46+
3. **示例代码**：提供完整可运行的示例
47+
4. **版本信息**：显示 npm 版本和下载量徽章
48+
5. **外部依赖**：明确说明基于的第三方库
49+
50+
### 参考示例
51+
- **完整示例**：[viewport.md](mdc:src/plugins/viewport.md) - 展示了完整的插件文档结构
52+
- **配置表格**：详细的参数说明表格
53+
- **多语言支持**：中英文对照的配置说明
54+
55+
### 配置参数文档化
56+
对于复杂的配置对象：
57+
1. **分层说明**：主要参数 → 子属性 → 具体选项
58+
2. **类型定义**：明确参数类型和默认值
59+
3. **使用场景**：说明何时使用该配置
60+
4. **相关链接**：引用官方文档或源码
61+
62+
### 文档质量检查
63+
- ✅ 所有配置参数都有说明
64+
- ✅ 代码示例可以直接使用
65+
- ✅ 中英文版本内容一致
66+
- ✅ 链接和引用正确有效

‎.cursor/rules/project-structure.mdc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
alwaysApply: true
3+
---
4+
5+
# WinJS 文档项目结构与语言设置
6+
7+
## 项目概述
8+
这是一个 VitePress 驱动的 WinJS 框架文档网站，支持中英文双语。
9+
10+
## 核心文件结构
11+
- 主配置：[.vitepress/config.ts](mdc:.vitepress/config.ts)
12+
- 主题样式：[.vitepress/theme/styles/](mdc:.vitepress/theme/styles/)
13+
- 英文文档：[src/](mdc:src/) 目录
14+
- 中文文档：[src/zh/](mdc:src/zh/) 目录
15+
16+
## 重要约定
17+
1. **语言设置**：始终使用中文回答用户问题
18+
2. **双语结构**：英文内容在 `src/`，中文内容在 `src/zh/`
19+
3. **配置参数**：所有配置都应该有英文和中文两版本的说明
20+
4. **主题色**：使用 VitePress 主题变量，主品牌色为 `#646cff`
21+
22+
## 文档类型
23+
- **指南**：[src/guides/](mdc:src/guides/) 和 [src/zh/guides/](mdc:src/zh/guides/)
24+
- **插件**：[src/plugins/](mdc:src/plugins/) 和 [src/zh/plugins/](mdc:src/zh/plugins/)
25+
- **API**：[src/api/](mdc:src/api/) 和 [src/zh/api/](mdc:src/zh/api/)
26+
- **配置**：[src/config/](mdc:src/config/) 和 [src/zh/config/](mdc:src/zh/config/)

‎.cursor/rules/theme-styles.mdc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
globs: *.css,*.vue
3+
---
4+
5+
# 主题样式开发指南
6+
7+
## VitePress 主题结构
8+
主题样式文件位于 [.vitepress/theme/styles/](mdc:.vitepress/theme/styles/) 目录：
9+
10+
### 样式文件组织
11+
- **入口文件**：[index.css](mdc:.vitepress/theme/styles/index.css) - 导入所有样式
12+
- **变量定义**：[vars.css](mdc:.vitepress/theme/styles/vars.css) - CSS 自定义属性
13+
- **页面样式**：[pages.css](mdc:.vitepress/theme/styles/pages.css)
14+
- **组件样式**：各个专用的 CSS 文件
15+
16+
### 主题色系统
17+
使用 VitePress CSS 变量：
18+
```css
19+
--vp-c-brand: #646cff; /* 主品牌色 */
20+
--vp-c-brand-light: #747bff; /* 浅色变体 */
21+
--vp-c-brand-dark: #535bf2; /* 深色变体 */
22+
--vp-c-brand-lighter: #9499ff; /* 更浅变体 */
23+
--vp-c-brand-darker: #454ce1; /* 更深变体 */
24+
```
25+
26+
### 样式开发规范
27+
1. **使用 CSS 变量**：优先使用 VitePress 提供的 CSS 变量
28+
2. **响应式设计**：考虑移动端和桌面端适配
29+
3. **深色模式**：使用 `.dark` 类选择器
30+
4. **模块化**：每个组件创建独立的 CSS 文件
31+
5. **导入顺序**：在 [index.css](mdc:.vitepress/theme/styles/index.css) 中按依赖关系导入
32+
33+
### 组件样式示例
34+
参考 [markdown-buttons.css](mdc:.vitepress/theme/styles/markdown-buttons.css) 的实现方式，展示了如何：
35+
- 使用主题变量
36+
- 支持深色模式
37+
- 实现响应式交互效果

0 commit comments

Comments
 (0)