diff --git a/README.md b/README.md index 98688df..841028b 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,10 @@ This repository is a monorepo managed by pnpm workspaces: - **[@objectdocs/cli](./packages/cli)**: The command-line interface for building and developing sites. - **[@objectdocs/site](./packages/site)**: The core Next.js application template. +## 📚 Examples + +- **[example](./example)**: A complete standalone project demonstrating CLI-created project structure. Use this to test Vercel deployment and validate that published npm packages work correctly outside the monorepo. + ## 🤝 Contributing Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. diff --git a/example/.gitignore b/example/.gitignore new file mode 100644 index 0000000..7933a4d --- /dev/null +++ b/example/.gitignore @@ -0,0 +1,36 @@ +# Dependencies +node_modules/ +.pnp +.pnp.js + +# Testing +coverage/ + +# Next.js +.next/ +out/ + +# Production +build/ +dist/ + +# Misc +.DS_Store +*.pem + +# Debug +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Local env files +.env +.env*.local + +# Vercel +.vercel + +# TypeScript +*.tsbuildinfo +next-env.d.ts diff --git a/example/ARCHITECTURE.md b/example/ARCHITECTURE.md new file mode 100644 index 0000000..2635b9a --- /dev/null +++ b/example/ARCHITECTURE.md @@ -0,0 +1,254 @@ +# Architecture Notes for @objectdocs/site Reference + +This document explains how the ObjectDocs CLI references and uses `@objectdocs/site`, and potential alternative approaches for different deployment scenarios. + +## Current Approach + +### How It Works + +The CLI (`@objectdocs/cli`) depends on `@objectdocs/site` as a regular npm dependency: + +```json +// packages/cli/package.json +{ + "dependencies": { + "@objectdocs/site": "workspace:*" // Converted to "0.2.11" when published + } +} +``` + +When commands run (dev, build, start), they resolve the site package location: + +```javascript +// packages/cli/src/commands/dev.mjs +let nextAppDir; +try { + nextAppDir = path.dirname(require.resolve('@objectdocs/site/package.json')); +} catch (e) { + // Fallback for local development + nextAppDir = path.resolve(__dirname, '../../../site'); +} +``` + +This approach: +- ✅ Works in monorepo (falls back to relative path) +- ✅ Works when installed from npm (resolves from node_modules) +- ✅ Keeps the site package decoupled from user projects +- ✅ Allows easy updates via npm + +### Published Package Structure + +When `@objectdocs/site` is published, it includes: + +``` +@objectdocs/site/ +├── package.json +├── next.config.mjs +├── app/ +│ ├── layout.tsx +│ ├── page.tsx +│ └── [lang]/docs/[[...slug]]/page.tsx +├── lib/ +├── middleware.ts +├── source.config.ts +└── ... +``` + +The CLI runs Next.js commands (dev, build, start) directly in this package directory. + +## Why This Approach Works + +1. **Clean Separation**: User projects only need content, not Next.js config +2. **Easy Updates**: Update CLI → automatically updates site engine +3. **Consistent Behavior**: All users get the same site functionality +4. **Simple Setup**: No need to scaffold Next.js files + +## Potential Issues and Solutions + +### Issue 1: Vercel Cannot Find @objectdocs/site + +**Symptom**: Build fails with "Cannot find module '@objectdocs/site'" + +**Cause**: +- CLI package.json has incorrect dependency reference +- npm/pnpm didn't resolve workspace reference correctly during publish + +**Solution**: +- Verify published CLI has correct dependency: `npm view @objectdocs/cli dependencies` +- Should show `"@objectdocs/site": "0.2.11"` not `"workspace:*"` +- If incorrect, republish with proper workspace protocol resolution + +### Issue 2: Next.js Config Not Found + +**Symptom**: "Could not find next.config.js" + +**Cause**: +- Package files filter excludes necessary files +- .gitignore accidentally ignores published files + +**Solution**: +- Add `files` field to site package.json: + ```json + { + "files": [ + "app", + "lib", + "public", + "*.mjs", + "*.ts", + "*.tsx", + "*.json" + ] + } + ``` + +### Issue 3: Build Output Not Found + +**Symptom**: Build succeeds but .next directory is empty + +**Cause**: CLI copies build output, but paths are incorrect + +**Solution**: Already handled in build.mjs with proper path resolution + +## Alternative Approaches Considered + +### Approach 1: Copy Site Files to User Project (Rejected) + +**Idea**: CLI scaffolds entire Next.js app in user's project + +**Pros**: +- More transparent (users see all files) +- No node_modules dependency resolution needed + +**Cons**: +- ❌ Much harder to update (users have modified files) +- ❌ Breaks "configuration as code" philosophy +- ❌ Huge initial scaffolding +- ❌ Users need to understand Next.js + +**Verdict**: Rejected - goes against core philosophy + +### Approach 2: Bundle Site in CLI (Rejected) + +**Idea**: Bundle @objectdocs/site directly into CLI package + +**Pros**: +- Single package to install +- No dependency resolution issues + +**Cons**: +- ❌ Huge package size +- ❌ Can't update site without updating CLI +- ❌ Makes development harder + +**Verdict**: Rejected - poor developer experience + +### Approach 3: Peer Dependency (Rejected) + +**Idea**: Make @objectdocs/site a peer dependency + +**Pros**: +- User explicitly installs site package +- Version control flexibility + +**Cons**: +- ❌ More complex setup for users +- ❌ Can lead to version mismatches +- ❌ Defeats purpose of simple CLI + +**Verdict**: Rejected - too complex for users + +### Approach 4: Dynamic Import (Possible Future) + +**Idea**: Download site package on first run if not present + +**Pros**: +- Smaller initial CLI package +- Can cache multiple versions + +**Cons**: +- Complex implementation +- Slower first run +- Network dependency + +**Verdict**: Consider for future if other issues arise + +## Current Solution: Hybrid Approach ✅ + +The current approach (dependency + fallback) is optimal: + +```javascript +let nextAppDir; +try { + // Production: resolve from node_modules + nextAppDir = path.dirname(require.resolve('@objectdocs/site/package.json')); +} catch (e) { + // Development: fallback to monorepo + nextAppDir = path.resolve(__dirname, '../../../site'); +} +``` + +**Why it's best**: +- ✅ Works in both development and production +- ✅ Simple for users (just install CLI) +- ✅ Easy to update +- ✅ Clean separation of concerns +- ✅ Standard npm dependency resolution + +## Vercel-Specific Considerations + +Vercel deploys work because: + +1. **Dependency Resolution**: Vercel runs `pnpm install` which installs `@objectdocs/cli` and its dependencies (including `@objectdocs/site`) + +2. **Build Command**: `pnpm build` → `objectdocs build` resolves site from node_modules + +3. **Node Modules**: All packages are available in Vercel's build environment + +4. **Output**: Build copies .next to project root, which Vercel deploys + +**No special configuration needed!** + +## Testing Standalone Installation + +To verify the approach works outside the monorepo: + +```bash +# Create test directory +mkdir /tmp/test-objectdocs +cd /tmp/test-objectdocs + +# Install CLI from npm +pnpm init +pnpm add -D @objectdocs/cli + +# Verify site is installed +ls -la node_modules/@objectdocs/site + +# Create content +mkdir -p content/docs +echo '{"pages":["index"]}' > content/docs/meta.json +echo '---\ntitle: Test\n---\n# Test' > content/docs/index.mdx + +# Test +pnpm exec objectdocs build +``` + +## Recommendations + +1. **For maintainers**: Keep the current approach, ensure proper publishing + +2. **For users**: Just install `@objectdocs/cli`, everything else is automatic + +3. **For Vercel**: No special configuration needed, standard Next.js deployment works + +4. **For debugging**: Check that `@objectdocs/site` is in `node_modules` and has all app files + +## Conclusion + +The current architecture is sound. Any deployment issues are likely due to: +- Incorrect package publishing (workspace:* not resolved) +- User project configuration errors +- Network/registry issues + +The `example` folder demonstrates the correct setup and can be used to validate deployments. diff --git a/example/INDEX.md b/example/INDEX.md new file mode 100644 index 0000000..5c1ca60 --- /dev/null +++ b/example/INDEX.md @@ -0,0 +1,227 @@ +# Example Folder - Complete Guide + +欢迎查看 ObjectDocs 示例项目！这是一个完整的、独立的文档项目，展示了如何使用 ObjectDocs CLI 创建和部署文档站点。 + +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. + +## 🎯 Purpose / 目的 + +这个示例项目的主要目的： + +This example project serves these key purposes: + +1. **Vercel 部署测试** / **Vercel Deployment Testing** + - 验证使用 CLI 创建的项目可以成功部署到 Vercel + - Validate that CLI-created projects can successfully deploy to Vercel + - 测试 `@objectdocs/site` 包引用方式是否正确 + - Test that the `@objectdocs/site` package reference approach works correctly + +2. **独立项目示例** / **Standalone Project Example** + - 展示真实用户如何创建文档项目 + - Show how real users would create documentation projects + - 使用发布到 npm 的包，而不是 workspace 引用 + - Use published npm packages instead of workspace references + +3. **文档和测试参考** / **Documentation and Testing Reference** + - 提供完整的设置说明和最佳实践 + - Provide complete setup instructions and best practices + - 包含验证脚本确保配置正确 + - Include validation scripts to ensure correct configuration + +## 📚 Documentation Files / 文档文件 + +The example includes comprehensive documentation: + +### README.md +主要文档，包括： +- Project overview and purpose +- Quick start guide +- Deployment instructions +- Troubleshooting guide + +### ARCHITECTURE.md +架构文档，解释： +- How `@objectdocs/site` is referenced by the CLI +- Why the current approach works +- Alternative approaches considered +- Vercel deployment considerations +- Technical details for maintainers + +### VERCEL.md +Vercel 部署指南，包括： +- Step-by-step deployment instructions +- Configuration options +- Troubleshooting common issues +- Production optimization tips + +### TESTING.md +测试指南，说明如何： +- Test outside the monorepo context +- Validate standalone installations +- Use automated testing scripts +- Ensure correct behavior before deployment + +## 🏗️ Project Structure / 项目结构 + +``` +example/ +├── README.md # Main documentation +├── ARCHITECTURE.md # Technical architecture details +├── VERCEL.md # Vercel deployment guide +├── TESTING.md # Testing guide +├── validate.sh # Validation script +├── package.json # Uses @objectdocs/cli from npm +├── vercel.json # Vercel configuration +├── .gitignore # Git ignore rules +├── content/ +│ ├── docs.site.json # Global site configuration +│ └── docs/ +│ ├── meta.json # Sidebar navigation +│ ├── index.mdx # Home page +│ ├── getting-started.mdx +│ └── configuration.mdx +└── public/ + └── README.md # Static assets instructions +``` + +## 🚀 Quick Start / 快速开始 + +### 1. 安装依赖 / Install Dependencies + +```bash +cd example +pnpm install +``` + +### 2. 验证配置 / Validate Setup + +```bash +bash validate.sh +``` + +### 3. 启动开发服务器 / Start Development Server + +```bash +pnpm dev +``` + +访问 http://localhost:7777 + +### 4. 构建生产版本 / Build for Production + +```bash +pnpm build +``` + +### 5. 部署到 Vercel / Deploy to Vercel + +查看 VERCEL.md 获取详细说明 / See VERCEL.md for detailed instructions + +## ✅ Validation Checklist / 验证清单 + +使用这个清单确保项目设置正确： + +Use this checklist to ensure the project is set up correctly: + +- [ ] `pnpm install` 成功完成 / completes without errors +- [ ] `bash validate.sh` 所有检查通过 / all checks pass +- [ ] `pnpm dev` 启动开发服务器 / starts development server +- [ ] 所有页面在浏览器中正常加载 / all pages load correctly in browser +- [ ] 导航功能正常（侧边栏、头部链接）/ navigation works (sidebar, header links) +- [ ] `pnpm build` 构建成功 / build completes successfully +- [ ] `pnpm start` 启动生产服务器 / starts production server +- [ ] 部署到 Vercel 成功 / deployment to Vercel succeeds +- [ ] 部署后的网站完全正常 / deployed site is fully functional + +## 🔑 Key Differences from `examples/starter` / 与 `examples/starter` 的主要区别 + +| Aspect | examples/starter | example | +|--------|-----------------|---------| +| Purpose | Quick start template | Full deployment testing | +| Dependencies | `workspace:*` | Published npm packages | +| Documentation | Basic README | Comprehensive guides | +| Validation | None | Automated script | +| Context | Part of monorepo | Standalone project | +| Target | Quick prototyping | Production deployment | + +## 🐛 Troubleshooting / 故障排除 + +### 问题：在 monorepo 中测试 +### Issue: Testing in Monorepo + +由于这个示例在 monorepo 中，pnpm 可能会解析到 workspace 包。要正确测试： + +Since this example is in a monorepo, pnpm might resolve to workspace packages. To test correctly: + +```bash +# 复制到 monorepo 外部 +# Copy outside monorepo +cp -r example /tmp/objectdocs-test +cd /tmp/objectdocs-test +pnpm install +``` + +参考 TESTING.md 获取更多测试方法。 +See TESTING.md for more testing methods. + +### 问题：Vercel 部署失败 +### Issue: Vercel Deployment Fails + +1. 检查 `@objectdocs/cli` 是否使用正确的版本号 + Check that `@objectdocs/cli` uses correct version number +2. 确认所有内容文件已提交到 Git + Confirm all content files are committed to Git +3. 查看 VERCEL.md 中的故障排除部分 + See troubleshooting section in VERCEL.md + +## 🤝 Contributing / 贡献 + +如果发现问题或有改进建议： + +If you find issues or have improvements: + +1. 在此示例中测试更改 + Test changes in this example first +2. 确保部署仍然正常 + Ensure deployment still works +3. 提交清晰的 PR 说明 + Submit PR with clear description + +## 📄 License / 许可证 + +MIT - Same as the main ObjectDocs project + +--- + +## For Maintainers / 维护者须知 + +### Publishing Checklist + +在发布新版本前，使用此示例验证： + +Before publishing new versions, use this example to validate: + +1. ✅ Update version in packages/cli/package.json and packages/site/package.json +2. ✅ Build packages: `pnpm build` +3. ✅ Test in example: `cd example && pnpm install && bash validate.sh` +4. ✅ Test build: `pnpm build` in example +5. ✅ Publish packages: `pnpm changeset publish` +6. ✅ Test with published versions (see TESTING.md) +7. ✅ Deploy to Vercel to verify production deployment + +### Updating the Example + +When updating example content: + +1. Keep it simple and focused +2. Ensure all pages have proper frontmatter +3. Update meta.json if adding/removing pages +4. Run validation script +5. Test both dev and build + +### Common Maintenance Tasks + +- **Update dependencies**: `pnpm up -r @objectdocs/cli` +- **Add new page**: Create MDX + update meta.json +- **Change config**: Edit docs.site.json +- **Test deployment**: Follow VERCEL.md instructions diff --git a/example/README.md b/example/README.md new file mode 100644 index 0000000..7d4d159 --- /dev/null +++ b/example/README.md @@ -0,0 +1,206 @@ +# ObjectDocs Example Project + +This is an **example project** that demonstrates how a documentation site created with the ObjectDocs CLI works in a real-world scenario. It's designed to test and validate deployment on platforms like Vercel. + +## 📋 Purpose + +This example serves multiple purposes: + +1. **Testing Reference**: Validate that CLI-created projects can be deployed successfully +2. **Deployment Guide**: Demonstrate the correct setup for production deployments +3. **Integration Test**: Ensure `@objectdocs/cli` and `@objectdocs/site` work together correctly when installed from npm (not workspace) + +## 🎯 Key Differences from `examples/starter` + +- **Real npm packages**: Uses `@objectdocs/cli` from npm registry (not `workspace:*`) +- **Standalone setup**: Completely independent from the monorepo +- **Vercel-ready**: Configured for deployment on Vercel and other platforms +- **Production representative**: Mirrors exactly how a user would create a project + +## 📁 Project Structure + +``` +example/ +├── content/ +│ ├── docs.site.json # Global site configuration +│ └── docs/ +│ ├── meta.json # Sidebar navigation structure +│ ├── index.mdx # Home page +│ ├── getting-started.mdx +│ └── configuration.mdx +├── public/ # Static assets (logos, images) +├── package.json # Uses @objectdocs/cli from npm +└── README.md # This file +``` + +## 🚀 Getting Started + +### Prerequisites + +- Node.js 18+ +- pnpm (recommended) or npm + +### Installation + +1. Navigate to the example directory: + +```bash +cd example +``` + +2. Install dependencies: + +```bash +pnpm install +``` + +This will install `@objectdocs/cli` from npm, which in turn will pull `@objectdocs/site` as a dependency. + +### Development + +Start the development server: + +```bash +pnpm dev +``` + +The site will be available at [http://localhost:7777](http://localhost:7777). + +### Building + +Build the project for production: + +```bash +pnpm build +``` + +This will generate the production build in the `.next` directory. + +### Production Server + +Start the production server: + +```bash +pnpm start +``` + +### Validation + +Run the validation script to check your project setup: + +```bash +bash validate.sh +``` + +This will verify: +- ✅ Package.json configuration +- ✅ Content structure +- ✅ MDX frontmatter +- ✅ Dependencies +- ✅ Vercel configuration +- ✅ Git ignore settings + +## 🌐 Deploying to Vercel + +### Method 1: Using Vercel CLI + +1. Install Vercel CLI: + +```bash +npm i -g vercel +``` + +2. Deploy from the example directory: + +```bash +cd example +vercel +``` + +### Method 2: Using GitHub Integration + +1. Push this example to your GitHub repository +2. Import the project in Vercel +3. Set the **Root Directory** to `example` +4. Vercel will auto-detect Next.js settings + +### Vercel Configuration + +No special configuration is needed. Vercel will automatically: +- Detect the Next.js framework +- Use `pnpm build` (via `objectdocs build`) as the build command +- Use the `.next` directory as the output + +## ✅ Testing Checklist + +Use this checklist to validate the example works correctly: + +- [ ] `pnpm install` completes without errors +- [ ] `pnpm dev` starts the development server +- [ ] All pages load correctly in the browser +- [ ] Navigation works (sidebar, header links) +- [ ] `pnpm build` completes successfully +- [ ] `pnpm start` serves the production build +- [ ] Deployment to Vercel succeeds +- [ ] Deployed site is fully functional + +## 🔧 Troubleshooting + +### Issue: "Cannot find module '@objectdocs/site'" + +**Solution**: Make sure you're using the published version of `@objectdocs/cli` from npm, not a workspace reference. + +### Issue: Vercel build fails + +**Possible causes**: +1. Using `workspace:*` reference instead of npm version +2. Missing or incorrect `package.json` scripts +3. Node.js version incompatibility + +**Solution**: +- Check that `package.json` uses `"@objectdocs/cli": "^0.2.11"` (or latest version) +- Ensure build script is `"build": "objectdocs build"` +- Verify Node.js version is 18+ + +### Issue: Broken links or missing content + +**Solution**: +- Verify all pages listed in `meta.json` have corresponding `.mdx` files +- Check that file names match exactly (case-sensitive) +- Ensure frontmatter includes both `title` and `description` + +## 📝 Notes for Development + +### Updating CLI Version + +When a new version of `@objectdocs/cli` is published: + +```bash +pnpm up @objectdocs/cli +``` + +### Adding New Pages + +1. Create a new `.mdx` file in `content/docs/` +2. Add the page slug to `content/docs/meta.json` +3. Include proper frontmatter in the MDX file + +### Customizing Branding + +Edit `content/docs.site.json` to change: +- Site name +- Logo images +- Navigation links +- Build output type + +## 🤝 Contributing + +This example is part of the ObjectDocs project. If you find issues or have improvements: + +1. Test your changes in this example first +2. Ensure deployment still works +3. Submit a PR with clear description + +## 📄 License + +MIT - Same as the main ObjectDocs project diff --git a/example/TESTING.md b/example/TESTING.md new file mode 100644 index 0000000..028aa42 --- /dev/null +++ b/example/TESTING.md @@ -0,0 +1,165 @@ +# Testing Outside Monorepo + +To properly test the example as a standalone project (simulating a real user's setup), you need to test it outside the monorepo context. + +## Why This Matters + +Inside the monorepo: +- pnpm workspace resolution may interfere +- Dependencies might resolve to workspace packages instead of npm +- The test doesn't accurately represent a user's experience + +## How to Test Properly + +### Method 1: Test in a separate directory + +1. Copy the example folder to a location outside the monorepo: + +```bash +# From the monorepo root +cp -r example /tmp/objectdocs-test +cd /tmp/objectdocs-test +``` + +2. Install dependencies fresh: + +```bash +pnpm install +``` + +3. Run the development server: + +```bash +pnpm dev +``` + +4. Build for production: + +```bash +pnpm build +``` + +### Method 2: Test via npm pack (Recommended for CI) + +This method is closer to how users would install from npm: + +1. Build and pack the CLI package: + +```bash +cd packages/cli +pnpm pack +# This creates objectdocs-cli-0.2.11.tgz +``` + +2. Create a test directory: + +```bash +mkdir /tmp/test-standalone +cd /tmp/test-standalone +``` + +3. Initialize and install from the packed tarball: + +```bash +pnpm init +pnpm add -D ../path/to/objectdocs-cli-0.2.11.tgz +``` + +4. Copy the content structure: + +```bash +cp -r /path/to/example/content . +``` + +5. Add scripts to package.json and test. + +### Method 3: Test with published npm version + +Once the packages are published to npm: + +```bash +mkdir /tmp/test-npm +cd /tmp/test-npm +pnpm init +pnpm add -D @objectdocs/cli +# Copy content directory +pnpm dev +``` + +## Verifying Correct Behavior + +When testing outside the monorepo, verify: + +1. ✅ `@objectdocs/cli` installs from npm (or tarball) +2. ✅ `@objectdocs/site` is pulled as a dependency of the CLI +3. ✅ Development server starts without errors +4. ✅ Build completes successfully +5. ✅ Generated output is correct (.next or out directory) +6. ✅ Production server runs without issues + +## Common Issues + +### Issue: "Cannot find module '@objectdocs/site'" + +This happens when: +- The CLI package.json has `workspace:*` for `@objectdocs/site` +- Solution: Ensure published version has proper version number + +### Issue: Different behavior in monorepo vs standalone + +This is expected due to workspace resolution. Always test in standalone mode before release. + +## Automated Testing Script + +Create this script for CI/CD testing: + +```bash +#!/bin/bash +set -e + +echo "Testing ObjectDocs standalone installation..." + +# Create temp directory +TEST_DIR=$(mktemp -d) +cd "$TEST_DIR" + +# Initialize project +npm init -y + +# Install CLI +npm install -D @objectdocs/cli@latest + +# Create content structure +mkdir -p content/docs +cat > content/docs.site.json << 'EOF' +{ + "branding": { "name": "Test Site" } +} +EOF + +cat > content/docs/meta.json << 'EOF' +{ + "pages": ["index"] +} +EOF + +cat > content/docs/index.mdx << 'EOF' +--- +title: Test +description: Test page +--- +# Test +EOF + +# Add scripts +npm pkg set scripts.dev="objectdocs dev" +npm pkg set scripts.build="objectdocs build" + +# Test build +echo "Running build..." +npm run build + +echo "✅ Standalone test passed!" +``` + +Save as `test-standalone.sh` and run with `bash test-standalone.sh`. diff --git a/example/VERCEL.md b/example/VERCEL.md new file mode 100644 index 0000000..5954100 --- /dev/null +++ b/example/VERCEL.md @@ -0,0 +1,239 @@ +# Vercel Deployment Guide + +This guide explains how to deploy the ObjectDocs example project (or any CLI-created project) to Vercel. + +## Prerequisites + +- A Vercel account (free tier works) +- A GitHub/GitLab/Bitbucket repository (or use Vercel CLI) +- Node.js 18+ configured in Vercel + +## Deployment Methods + +### Method 1: Via Vercel Dashboard (Recommended) + +1. **Push to Git Repository** + ```bash + git init + git add . + git commit -m "Initial commit" + git remote add origin https://github.com/yourusername/your-docs.git + git push -u origin main + ``` + +2. **Import in Vercel** + - Go to [vercel.com/new](https://vercel.com/new) + - Select your repository + - Configure project settings: + - **Framework Preset**: Next.js (auto-detected) + - **Root Directory**: `.` (or `example` if in monorepo) + - **Build Command**: `pnpm build` (auto-detected from package.json) + - **Output Directory**: `.next` (auto-detected) + - **Install Command**: `pnpm install` + +3. **Deploy** + - Click "Deploy" + - Vercel will build and deploy your site + +### Method 2: Via Vercel CLI + +1. **Install Vercel CLI** + ```bash + npm i -g vercel + ``` + +2. **Deploy from example directory** + ```bash + cd example + vercel + ``` + +3. **Follow the prompts** + - Link to existing project or create new + - Configure settings (or use defaults) + +4. **Deploy to production** + ```bash + vercel --prod + ``` + +## Configuration + +### vercel.json (Optional) + +The example includes a `vercel.json` file with recommended settings: + +```json +{ + "buildCommand": "pnpm build", + "devCommand": "pnpm dev", + "installCommand": "pnpm install", + "framework": "nextjs", + "outputDirectory": ".next" +} +``` + +These settings help Vercel auto-detect the correct build configuration. + +### Environment Variables + +If using AI translation or other features: + +1. Go to Project Settings → Environment Variables +2. Add required variables: + - `OPENAI_API_KEY` (for translation) + - `OPENAI_BASE_URL` (optional, for custom endpoints) + +### Build Settings + +Vercel auto-detects Next.js projects. If you need custom settings: + +- **Framework**: Next.js +- **Node.js Version**: 18.x or 20.x +- **Package Manager**: pnpm (recommended) or npm +- **Build Command**: `pnpm build` or `objectdocs build` +- **Output Directory**: `.next` + +## Troubleshooting Vercel Deployment + +### Issue 1: "Cannot find module '@objectdocs/site'" + +**Cause**: The CLI package.json uses `workspace:*` reference instead of npm version. + +**Solution**: +- Ensure `@objectdocs/cli` package.json has proper dependency: + ```json + { + "dependencies": { + "@objectdocs/site": "^0.2.11" // NOT "workspace:*" + } + } + ``` +- Republish the CLI package if needed + +### Issue 2: Build fails with "Module not found" + +**Cause**: Missing dependencies or incorrect package resolution. + +**Solution**: +```bash +# Clear lock file and reinstall +rm -rf node_modules pnpm-lock.yaml +pnpm install +``` + +### Issue 3: "next: command not found" + +**Cause**: The CLI can't locate Next.js from `@objectdocs/site`. + +**Solution**: +- Check that `@objectdocs/site` is properly installed as a dependency of `@objectdocs/cli` +- Verify the CLI's require.resolve logic in dev.mjs and build.mjs + +### Issue 4: Site builds but pages are blank + +**Cause**: Content directory not found or `DOCS_DIR` env var incorrect. + +**Solution**: +- Ensure `content/docs/` exists with proper structure +- Check that `meta.json` and `.mdx` files are committed +- Verify frontmatter in MDX files is correct + +### Issue 5: Deployment succeeds but runtime errors + +**Cause**: Production build has different behavior than dev. + +**Solution**: +- Test production build locally first: + ```bash + pnpm build + pnpm start + ``` +- Check Vercel function logs in dashboard +- Verify all dependencies are in `dependencies` not `devDependencies` + +## Verifying Successful Deployment + +After deployment, verify: + +1. ✅ Site loads at the Vercel URL +2. ✅ All pages are accessible +3. ✅ Navigation works (sidebar, header links) +4. ✅ Dark mode toggle works +5. ✅ Search functionality works (if enabled) +6. ✅ Images and assets load correctly +7. ✅ No console errors in browser + +## Production Optimization + +### 1. Static Site Generation (SSG) + +For better performance, configure static export in `content/docs.site.json`: + +```json +{ + "build": { + "output": "export" + } +} +``` + +This generates static HTML files that deploy faster and cost less. + +### 2. Image Optimization + +Place images in the `public/` directory and reference them with absolute paths: + +```markdown +![Logo](/images/logo.png) +``` + +### 3. Custom Domain + +1. Go to Project Settings → Domains +2. Add your custom domain +3. Configure DNS records as instructed + +## Continuous Deployment + +Once connected to Git: + +1. **Automatic Deploys**: Push to main branch triggers production deployment +2. **Preview Deploys**: Pull requests get preview URLs +3. **Rollback**: Easy rollback to previous deployments in dashboard + +## Cost Considerations + +- **Free Tier**: Suitable for documentation sites + - 100GB bandwidth/month + - Serverless function execution + - Automatic HTTPS + +- **Pro Tier**: For larger sites or teams + - 1TB bandwidth/month + - Advanced analytics + - Team collaboration + +## Next Steps + +- Configure custom domain +- Set up preview deployments for PRs +- Add analytics (Vercel Analytics or Google Analytics) +- Optimize images and assets +- Set up monitoring and alerts + +## Support + +If you encounter issues: + +1. Check [Vercel Documentation](https://vercel.com/docs) +2. Review [Next.js Deployment Guide](https://nextjs.org/docs/deployment) +3. Open an issue in the ObjectDocs repository +4. Contact Vercel support (Pro tier) + +## Example Deployment URLs + +After deployment, your site will be available at: +- Production: `https://your-project.vercel.app` +- Custom Domain: `https://docs.yourcompany.com` (if configured) +- Preview: `https://your-project-git-branch.vercel.app` (for branches) diff --git a/example/content/docs.site.json b/example/content/docs.site.json new file mode 100644 index 0000000..2e797f9 --- /dev/null +++ b/example/content/docs.site.json @@ -0,0 +1,23 @@ +{ + "branding": { + "name": "ObjectDocs Example", + "logo": { + "light": "/logo.svg", + "dark": "/logo-dark.svg" + } + }, + "links": [ + { + "text": "Documentation", + "url": "/docs" + }, + { + "text": "GitHub", + "url": "https://github.com/objectstack-ai/objectdocs", + "icon": "github" + } + ], + "build": { + "output": "standalone" + } +} diff --git a/example/content/docs/configuration.mdx b/example/content/docs/configuration.mdx new file mode 100644 index 0000000..7485286 --- /dev/null +++ b/example/content/docs/configuration.mdx @@ -0,0 +1,151 @@ +--- +title: Configuration +description: Learn how to configure your ObjectDocs site +--- + +# Configuration + +ObjectDocs uses a "Configuration as Code" approach where all site settings are defined in JSON files. + +## Global Configuration + +The global site configuration is defined in `content/docs.site.json`: + +```json +{ + "branding": { + "name": "My Docs Site", + "logo": { + "light": "/logo.svg", + "dark": "/logo-dark.svg" + } + }, + "links": [ + { + "text": "Documentation", + "url": "/docs" + }, + { + "text": "GitHub", + "url": "https://github.com/username/repo", + "icon": "github" + } + ], + "build": { + "output": "standalone" + } +} +``` + +### Branding Options + +- **name**: The name of your documentation site +- **logo.light**: Path to the logo for light mode +- **logo.dark**: Path to the logo for dark mode + +### Navigation Links + +The `links` array defines the navigation bar links: + +- **text**: Link text +- **url**: Link URL +- **icon**: Optional icon name (e.g., "github", "twitter") + +### Build Options + +- **output**: Build output type + - `"standalone"`: Server-side rendering (default) + - `"export"`: Static site generation + +## Sidebar Navigation + +Each directory can have a `meta.json` file to control the sidebar structure: + +```json +{ + "title": "Getting Started", + "pages": [ + "introduction", + "---Installation---", + "quick-start", + "configuration" + ] +} +``` + +### Meta.json Options + +- **title**: Section title in the sidebar +- **pages**: Array of page slugs in the desired order + - Use `"---Title---"` to create section separators + +## Page Frontmatter + +Each MDX file should include frontmatter: + +```mdx +--- +title: Page Title +description: Page description for SEO +--- + +# Page Content +``` + +### Frontmatter Options + +- **title**: Page title (required) +- **description**: Page description for SEO (required) + +### Available Components + +ObjectDocs provides Fumadocs UI components globally. No imports needed: + +- **Callout**: `...` +- **Cards/Card**: `...` +- **Steps/Step**: `...` +- **Tabs/Tab**: For tabbed content + +Example: + +```mdx + +Always include both `title` and `description` in your frontmatter for proper SEO and navigation. + + +## Environment Variables + +ObjectDocs supports the following environment variables: + +- **DOCS_DIR**: Override the default content directory +- **PORT**: Override the default port (7777) +- **OPENAI_API_KEY**: API key for AI translation feature +- **OPENAI_BASE_URL**: Custom OpenAI API endpoint + +## Deployment Configuration + +### Vercel + +For Vercel deployment, ensure your `package.json` includes: + +```json +{ + "scripts": { + "build": "objectdocs build", + "start": "objectdocs start" + } +} +``` + +Vercel will automatically detect Next.js and use the appropriate build commands. + +### Other Platforms + +For other platforms, you can use the generated build output: + +- **Standalone**: Use the `.next` directory with Node.js +- **Static Export**: Use the `out` directory with any static hosting + + +ObjectDocs is optimized for deployment on platforms that support Next.js, such as Vercel, Netlify, and AWS Amplify. + diff --git a/example/content/docs/getting-started.mdx b/example/content/docs/getting-started.mdx new file mode 100644 index 0000000..ae582ba --- /dev/null +++ b/example/content/docs/getting-started.mdx @@ -0,0 +1,102 @@ +--- +title: Getting Started +description: Learn how to get started with ObjectDocs +--- + +# Getting Started + +This guide will help you get started with ObjectDocs. + +## Installation + +First, create a new project directory and initialize it: + +```bash +mkdir my-docs +cd my-docs +pnpm init +``` + +## Install ObjectDocs CLI + +Add the ObjectDocs CLI as a dev dependency: + +```bash +pnpm add -D @objectdocs/cli +``` + +## Configure Scripts + +Add the following scripts to your `package.json`: + +```json +{ + "scripts": { + "dev": "objectdocs dev", + "build": "objectdocs build", + "start": "objectdocs start" + } +} +``` + +## Create Content Structure + +Create the basic directory structure: + +```bash +mkdir -p content/docs +``` + +## Add Your First Page + +Create `content/docs/index.mdx`: + +```mdx +--- +title: Welcome +description: My new docs site +--- + +# Hello World + +Welcome to ObjectDocs! +``` + +Create `content/docs/meta.json`: + +```json +{ + "pages": ["index"] +} +``` + +## Start Development Server + +Start the development server: + +```bash +pnpm dev +``` + +Visit [http://localhost:7777](http://localhost:7777) to see your site. + +{/* Note: Callout, Cards, Steps and other Fumadocs components are globally available */} + +The development server includes hot reload, so changes to your content will be reflected immediately. + + +## Build for Production + +When you're ready to deploy, build your site: + +```bash +pnpm build +``` + +This will generate the production build in the `.next` directory (or `out` directory if configured for static export). + +## Next Steps + +- Learn about [Configuration](/docs/configuration) options +- Explore the metadata-driven architecture +- Deploy your site to Vercel or other platforms diff --git a/example/content/docs/index.mdx b/example/content/docs/index.mdx new file mode 100644 index 0000000..7ac0082 --- /dev/null +++ b/example/content/docs/index.mdx @@ -0,0 +1,45 @@ +--- +title: Welcome to ObjectDocs +description: A modern documentation engine for the low-code era +--- + +# Welcome to ObjectDocs + +Welcome to the ObjectDocs example project! This demonstrates how a project created with the ObjectDocs CLI works in production. + +## What is ObjectDocs? + +ObjectDocs is a next-generation documentation engine built on: + +- **Next.js 14** (App Router) +- **Fumadocs** (documentation middleware) +- **Configuration as Code** philosophy + +## Key Features + +{/* ObjectDocs provides Fumadocs components globally - no imports needed */} + + + Control navigation, sidebars, and SEO entirely via JSON configuration files. + + + + Seamlessly embed interactive components within your Markdown. + + + + Built-in CLI command to automatically translate documentation using OpenAI. + + + + Polished interface with automatic dark mode and accessibility features. + + + +## Getting Started + +Check out the [Getting Started](/docs/getting-started) guide to learn how to use ObjectDocs. + +## Configuration + +Learn about [Configuration](/docs/configuration) options to customize your documentation site. diff --git a/example/content/docs/meta.json b/example/content/docs/meta.json new file mode 100644 index 0000000..a55bf4c --- /dev/null +++ b/example/content/docs/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Documentation", + "pages": ["index", "getting-started", "configuration"] +} diff --git a/example/package.json b/example/package.json new file mode 100644 index 0000000..ae07e2d --- /dev/null +++ b/example/package.json @@ -0,0 +1,14 @@ +{ + "name": "objectdocs-example", + "version": "0.1.0", + "private": true, + "description": "Example project created with ObjectDocs CLI", + "scripts": { + "dev": "objectdocs dev", + "build": "objectdocs build", + "start": "objectdocs start" + }, + "devDependencies": { + "@objectdocs/cli": "^0.2.11" + } +} diff --git a/example/public/README.md b/example/public/README.md new file mode 100644 index 0000000..f1a7004 --- /dev/null +++ b/example/public/README.md @@ -0,0 +1,10 @@ +# Logo Files + +Place your logo files here: + +- `logo.svg` - Logo for light mode +- `logo-dark.svg` - Logo for dark mode + +These files are referenced in `content/docs.site.json`. + +If you don't have custom logos, the site will display the text-based branding name instead. diff --git a/example/validate.sh b/example/validate.sh new file mode 100755 index 0000000..3e94e64 --- /dev/null +++ b/example/validate.sh @@ -0,0 +1,170 @@ +#!/bin/bash +# Test script for ObjectDocs example project +# This verifies the basic functionality of a CLI-created project + +set -e + +echo "================================================" +echo "ObjectDocs Example Project - Validation Script" +echo "================================================" +echo "" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Check if we're in the example directory +if [ ! -f "package.json" ] || ! grep -q "objectdocs-example" package.json; then + echo -e "${RED}Error: This script must be run from the example directory${NC}" + exit 1 +fi + +echo "Step 1: Checking package.json configuration..." +if grep -q '"dev": "objectdocs dev"' package.json; then + echo -e "${GREEN}✓${NC} Dev script configured correctly" +else + echo -e "${RED}✗${NC} Dev script missing or incorrect" + exit 1 +fi + +if grep -q '"build": "objectdocs build"' package.json; then + echo -e "${GREEN}✓${NC} Build script configured correctly" +else + echo -e "${RED}✗${NC} Build script missing or incorrect" + exit 1 +fi + +if grep -q '@objectdocs/cli' package.json; then + echo -e "${GREEN}✓${NC} CLI dependency present" +else + echo -e "${RED}✗${NC} CLI dependency missing" + exit 1 +fi + +echo "" +echo "Step 2: Checking content structure..." + +if [ -d "content/docs" ]; then + echo -e "${GREEN}✓${NC} Content directory exists" +else + echo -e "${RED}✗${NC} Content directory missing" + exit 1 +fi + +if [ -f "content/docs.site.json" ]; then + echo -e "${GREEN}✓${NC} Site configuration exists" +else + echo -e "${RED}✗${NC} Site configuration missing" + exit 1 +fi + +if [ -f "content/docs/meta.json" ]; then + echo -e "${GREEN}✓${NC} Meta configuration exists" +else + echo -e "${RED}✗${NC} Meta configuration missing" + exit 1 +fi + +# Count MDX files +MDX_COUNT=$(find content/docs -name "*.mdx" -type f | wc -l) +if [ "$MDX_COUNT" -gt 0 ]; then + echo -e "${GREEN}✓${NC} Found $MDX_COUNT MDX file(s)" +else + echo -e "${YELLOW}⚠${NC} No MDX files found" +fi + +echo "" +echo "Step 3: Validating MDX frontmatter..." + +# Check if at least one MDX file has proper frontmatter +VALID_MDX=0 +for file in content/docs/*.mdx; do + if [ -f "$file" ]; then + if grep -q "^---" "$file" && grep -q "^title:" "$file" && grep -q "^description:" "$file"; then + VALID_MDX=$((VALID_MDX + 1)) + fi + fi +done + +if [ "$VALID_MDX" -gt 0 ]; then + echo -e "${GREEN}✓${NC} $VALID_MDX file(s) have valid frontmatter" +else + echo -e "${YELLOW}⚠${NC} No files with valid frontmatter found" +fi + +echo "" +echo "Step 4: Checking dependencies..." + +if [ -d "node_modules" ]; then + echo -e "${GREEN}✓${NC} node_modules exists" + + if [ -d "node_modules/@objectdocs/cli" ] || [ -L "node_modules/@objectdocs/cli" ]; then + echo -e "${GREEN}✓${NC} @objectdocs/cli is installed" + else + echo -e "${YELLOW}⚠${NC} @objectdocs/cli not found in node_modules (might be in parent workspace)" + fi + + if [ -d "node_modules/@objectdocs/site" ] || [ -L "node_modules/@objectdocs/site" ]; then + echo -e "${GREEN}✓${NC} @objectdocs/site is installed" + else + echo -e "${YELLOW}⚠${NC} @objectdocs/site not found in node_modules (might be in parent workspace)" + fi +else + echo -e "${YELLOW}⚠${NC} node_modules not found. Run 'pnpm install' first" +fi + +echo "" +echo "Step 5: Checking Vercel configuration..." + +if [ -f "vercel.json" ]; then + echo -e "${GREEN}✓${NC} vercel.json exists" + + if grep -q '"framework": "nextjs"' vercel.json; then + echo -e "${GREEN}✓${NC} Framework set to Next.js" + fi + + if grep -q '"buildCommand"' vercel.json; then + echo -e "${GREEN}✓${NC} Build command configured" + fi +else + echo -e "${YELLOW}⚠${NC} vercel.json not found (optional but recommended)" +fi + +echo "" +echo "Step 6: Checking .gitignore..." + +if [ -f ".gitignore" ]; then + echo -e "${GREEN}✓${NC} .gitignore exists" + + if grep -q "node_modules" .gitignore; then + echo -e "${GREEN}✓${NC} node_modules ignored" + fi + + if grep -q ".next" .gitignore; then + echo -e "${GREEN}✓${NC} .next ignored" + fi +else + echo -e "${YELLOW}⚠${NC} .gitignore not found" +fi + +echo "" +echo "================================================" +echo "Validation Summary" +echo "================================================" +echo "" +echo "✅ All required files and configurations are present!" +echo "" +echo "Next steps:" +echo " 1. Install dependencies: pnpm install" +echo " 2. Start dev server: pnpm dev" +echo " 3. Build for production: pnpm build" +echo " 4. Deploy to Vercel" +echo "" +echo "For more information, see:" +echo " - README.md - Project overview and quick start" +echo " - TESTING.md - How to test standalone installations" +echo " - VERCEL.md - Vercel deployment guide" +echo " - ARCHITECTURE.md - Technical architecture details" +echo "" diff --git a/example/vercel.json b/example/vercel.json new file mode 100644 index 0000000..2c0d15f --- /dev/null +++ b/example/vercel.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://openapi.vercel.sh/vercel.json", + "buildCommand": "pnpm build", + "devCommand": "pnpm dev", + "installCommand": "pnpm install", + "framework": "nextjs", + "outputDirectory": ".next" +}