Skip to content

Commit 5b4ca5f

Browse files
Copilothuangyiirene
Copilot
and
huangyiirene
committed
Add comprehensive INDEX documentation for example folder
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent 039f773 commit 5b4ca5f

1 file changed

Lines changed: 227 additions & 0 deletions

File tree

‎example/INDEX.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Example Folder - Complete Guide
2+
3+
欢迎查看 ObjectDocs 示例项目！这是一个完整的、独立的文档项目，展示了如何使用 ObjectDocs CLI 创建和部署文档站点。
4+
5+
Welcome to the ObjectDocs example project! This is a complete, standalone documentation project that demonstrates how to create and deploy documentation sites using the ObjectDocs CLI.
6+
7+
## 🎯 Purpose / 目的
8+
9+
这个示例项目的主要目的：
10+
11+
This example project serves these key purposes:
12+
13+
1. **Vercel 部署测试** / **Vercel Deployment Testing**
14+
- 验证使用 CLI 创建的项目可以成功部署到 Vercel
15+
- Validate that CLI-created projects can successfully deploy to Vercel
16+
- 测试 `@objectdocs/site` 包引用方式是否正确
17+
- Test that the `@objectdocs/site` package reference approach works correctly
18+
19+
2. **独立项目示例** / **Standalone Project Example**
20+
- 展示真实用户如何创建文档项目
21+
- Show how real users would create documentation projects
22+
- 使用发布到 npm 的包，而不是 workspace 引用
23+
- Use published npm packages instead of workspace references
24+
25+
3. **文档和测试参考** / **Documentation and Testing Reference**
26+
- 提供完整的设置说明和最佳实践
27+
- Provide complete setup instructions and best practices
28+
- 包含验证脚本确保配置正确
29+
- Include validation scripts to ensure correct configuration
30+
31+
## 📚 Documentation Files / 文档文件
32+
33+
The example includes comprehensive documentation:
34+
35+
### README.md
36+
主要文档，包括：
37+
- Project overview and purpose
38+
- Quick start guide
39+
- Deployment instructions
40+
- Troubleshooting guide
41+
42+
### ARCHITECTURE.md
43+
架构文档，解释：
44+
- How `@objectdocs/site` is referenced by the CLI
45+
- Why the current approach works
46+
- Alternative approaches considered
47+
- Vercel deployment considerations
48+
- Technical details for maintainers
49+
50+
### VERCEL.md
51+
Vercel 部署指南，包括：
52+
- Step-by-step deployment instructions
53+
- Configuration options
54+
- Troubleshooting common issues
55+
- Production optimization tips
56+
57+
### TESTING.md
58+
测试指南，说明如何：
59+
- Test outside the monorepo context
60+
- Validate standalone installations
61+
- Use automated testing scripts
62+
- Ensure correct behavior before deployment
63+
64+
## 🏗️ Project Structure / 项目结构
65+
66+
```
67+
example/
68+
├── README.md # Main documentation
69+
├── ARCHITECTURE.md # Technical architecture details
70+
├── VERCEL.md # Vercel deployment guide
71+
├── TESTING.md # Testing guide
72+
├── validate.sh # Validation script
73+
├── package.json # Uses @objectdocs/cli from npm
74+
├── vercel.json # Vercel configuration
75+
├── .gitignore # Git ignore rules
76+
├── content/
77+
│ ├── docs.site.json # Global site configuration
78+
│ └── docs/
79+
│ ├── meta.json # Sidebar navigation
80+
│ ├── index.mdx # Home page
81+
│ ├── getting-started.mdx
82+
│ └── configuration.mdx
83+
└── public/
84+
└── README.md # Static assets instructions
85+
```
86+
87+
## 🚀 Quick Start / 快速开始
88+
89+
### 1. 安装依赖 / Install Dependencies
90+
91+
```bash
92+
cd example
93+
pnpm install
94+
```
95+
96+
### 2. 验证配置 / Validate Setup
97+
98+
```bash
99+
bash validate.sh
100+
```
101+
102+
### 3. 启动开发服务器 / Start Development Server
103+
104+
```bash
105+
pnpm dev
106+
```
107+
108+
访问 http://localhost:7777
109+
110+
### 4. 构建生产版本 / Build for Production
111+
112+
```bash
113+
pnpm build
114+
```
115+
116+
### 5. 部署到 Vercel / Deploy to Vercel
117+
118+
查看 VERCEL.md 获取详细说明 / See VERCEL.md for detailed instructions
119+
120+
## ✅ Validation Checklist / 验证清单
121+
122+
使用这个清单确保项目设置正确：
123+
124+
Use this checklist to ensure the project is set up correctly:
125+
126+
- [ ] `pnpm install` 成功完成 / completes without errors
127+
- [ ] `bash validate.sh` 所有检查通过 / all checks pass
128+
- [ ] `pnpm dev` 启动开发服务器 / starts development server
129+
- [ ] 所有页面在浏览器中正常加载 / all pages load correctly in browser
130+
- [ ] 导航功能正常（侧边栏、头部链接）/ navigation works (sidebar, header links)
131+
- [ ] `pnpm build` 构建成功 / build completes successfully
132+
- [ ] `pnpm start` 启动生产服务器 / starts production server
133+
- [ ] 部署到 Vercel 成功 / deployment to Vercel succeeds
134+
- [ ] 部署后的网站完全正常 / deployed site is fully functional
135+
136+
## 🔑 Key Differences from `examples/starter` / 与 `examples/starter` 的主要区别
137+
138+
| Aspect | examples/starter | example |
139+
|--------|-----------------|---------|
140+
| Purpose | Quick start template | Full deployment testing |
141+
| Dependencies | `workspace:*` | Published npm packages |
142+
| Documentation | Basic README | Comprehensive guides |
143+
| Validation | None | Automated script |
144+
| Context | Part of monorepo | Standalone project |
145+
| Target | Quick prototyping | Production deployment |
146+
147+
## 🐛 Troubleshooting / 故障排除
148+
149+
### 问题：在 monorepo 中测试
150+
### Issue: Testing in Monorepo
151+
152+
由于这个示例在 monorepo 中，pnpm 可能会解析到 workspace 包。要正确测试：
153+
154+
Since this example is in a monorepo, pnpm might resolve to workspace packages. To test correctly:
155+
156+
```bash
157+
# 复制到 monorepo 外部
158+
# Copy outside monorepo
159+
cp -r example /tmp/objectdocs-test
160+
cd /tmp/objectdocs-test
161+
pnpm install
162+
```
163+
164+
参考 TESTING.md 获取更多测试方法。
165+
See TESTING.md for more testing methods.
166+
167+
### 问题：Vercel 部署失败
168+
### Issue: Vercel Deployment Fails
169+
170+
1. 检查 `@objectdocs/cli` 是否使用正确的版本号
171+
Check that `@objectdocs/cli` uses correct version number
172+
2. 确认所有内容文件已提交到 Git
173+
Confirm all content files are committed to Git
174+
3. 查看 VERCEL.md 中的故障排除部分
175+
See troubleshooting section in VERCEL.md
176+
177+
## 🤝 Contributing / 贡献
178+
179+
如果发现问题或有改进建议：
180+
181+
If you find issues or have improvements:
182+
183+
1. 在此示例中测试更改
184+
Test changes in this example first
185+
2. 确保部署仍然正常
186+
Ensure deployment still works
187+
3. 提交清晰的 PR 说明
188+
Submit PR with clear description
189+
190+
## 📄 License / 许可证
191+
192+
MIT - Same as the main ObjectDocs project
193+
194+
---
195+
196+
## For Maintainers / 维护者须知
197+
198+
### Publishing Checklist
199+
200+
在发布新版本前，使用此示例验证：
201+
202+
Before publishing new versions, use this example to validate:
203+
204+
1. ✅ Update version in packages/cli/package.json and packages/site/package.json
205+
2. ✅ Build packages: `pnpm build`
206+
3. ✅ Test in example: `cd example && pnpm install && bash validate.sh`
207+
4. ✅ Test build: `pnpm build` in example
208+
5. ✅ Publish packages: `pnpm changeset publish`
209+
6. ✅ Test with published versions (see TESTING.md)
210+
7. ✅ Deploy to Vercel to verify production deployment
211+
212+
### Updating the Example
213+
214+
When updating example content:
215+
216+
1. Keep it simple and focused
217+
2. Ensure all pages have proper frontmatter
218+
3. Update meta.json if adding/removing pages
219+
4. Run validation script
220+
5. Test both dev and build
221+
222+
### Common Maintenance Tasks
223+
224+
- **Update dependencies**: `pnpm up -r @objectdocs/cli`
225+
- **Add new page**: Create MDX + update meta.json
226+
- **Change config**: Edit docs.site.json
227+
- **Test deployment**: Follow VERCEL.md instructions

0 commit comments

Comments
 (0)