Merge pull request #32 from objectstack-ai/copilot/initialize-package-json-in-content

Author: hotlong

README.md

@@ -55,56 +55,28 @@ This architecture allows developers and technical writers to manage complex, mul
 
 ## 🚀 Quick Start
 
-### 1. Create a new project
+### Option 1: In Any Existing Project (Recommended)
 
-Initialize your documentation site structure:
+Initialize ObjectDocs in any existing GitHub project without polluting the root directory:
 
 ```bash
-mkdir my-docs
-cd my-docs
-pnpm init
-pnpm add -D @objectdocs/cli
-```
-
-### 2. Configure scripts
-
-Add the following scripts to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "objectdocs dev",
-    "build": "objectdocs build",
-    "start": "objectdocs start"
-  }
-}
-```
-
-### 3. Initialize ObjectDocs
-
-Run the init command to set up the site engine:
-
-```bash
-pnpm objectdocs init
+cd your-existing-project
+npx @objectdocs/cli init
 ```
 
 This will:
+- Create `content/package.json` with necessary scripts
 - Copy the site engine to `content/.objectdocs`
-- Install necessary dependencies
-- Automatically add `content/.objectdocs` to `.gitignore`
-- Prepare your project for development
-
-### 4. Add content
+- Install dependencies in `content/.objectdocs/node_modules`
+- Automatically add `content/.objectdocs` and `content/node_modules` to `.gitignore`
+- Keep your project root clean and unpolluted
 
-Create the basic directory structure:
+Then add content and start the server:
 
 ```bash
 mkdir -p content/docs
-```
-
-Create `content/docs/index.mdx`:
 
-```mdx
+cat > content/docs/index.mdx << 'EOF'
 ---
 title: Welcome
 description: My new docs site
@@ -113,40 +85,76 @@ description: My new docs site
 # Hello World
 
 Welcome to ObjectDocs!
+EOF
+
+cat > content/docs/meta.json << 'EOF'
+{
+  "pages": ["index"]
+}
+EOF
+
+# Start the development server
+cd content && npm run dev
 ```
 
-Create `content/docs/meta.json`:
+Visit http://localhost:7777 to see your site.
+
+### Option 2: New Standalone Project
+
+For a new dedicated documentation project:
+
+```bash
+mkdir my-docs
+cd my-docs
+npm init -y
+npm install -D @objectdocs/cli
+```
+
+Add scripts to your root `package.json`:
 
 ```json
 {
-  "pages": ["index"]
+  "scripts": {
+    "dev": "cd content && npm run dev",
+    "build": "cd content && npm run build",
+    "start": "cd content && npm run start"
+  }
 }
 ```
 
-### 5. Start the server
+Initialize ObjectDocs:
 
 ```bash
-pnpm dev
+npm run init
+# or
+npx objectdocs init
 ```
 
-Visit http://localhost:7777 to see your site.
+Then follow the same steps as Option 1 to add content.
 
 ## 🏗️ Project Structure
 
 ObjectDocs enforces a clear directory structure to ensure maintainability at scale:
 
 ```text
 .
-├── content/               # [Data Layer] Raw Content
-│   ├── .objectdocs/       # Site engine (auto-generated by init)
+├── content/               # [Data Layer] All documentation files
+│   ├── package.json       # npm scripts (dev, build, start)
+│   ├── .objectdocs/       # Site engine (auto-generated, gitignored)
 │   ├── docs.site.json     # Global settings (Nav, Logo, Branding)
 │   └── docs/
 │       ├── meta.json      # Directory structure & sorting control
 │       └── index.mdx      # Documentation content
-├── package.json
+├── package.json           # (Optional) Root project package.json
 └── ...
 ```
 
+**Key Points:**
+- All documentation-related files are in `content/`
+- `content/.objectdocs/` is auto-generated and gitignored
+- Your project root remains clean
+- Perfect for adding docs to any existing project
+
 ## ⚙️ Configuration
 
 ObjectDocs is designed to be "Configuration as Code".

examples/starter/README.md

@@ -23,18 +23,25 @@ This starter template serves multiple purposes:
 ```
 examples/starter/
 ├── content/
-│   ├── .objectdocs/         # Site engine (created by init command)
-│   ├── docs.site.json       # Global site configuration
+│   ├── package.json          # npm scripts (auto-created by init)
+│   ├── .objectdocs/          # Site engine (created by init command, gitignored)
+│   ├── docs.site.json        # Global site configuration
 │   └── docs/
-│       ├── meta.json        # Sidebar navigation structure
-│       ├── index.mdx        # Home page
+│       ├── 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 workspace
-└── README.md               # This file
+├── public/                   # Static assets (logos, images)
+├── package.json              # Uses @objectdocs/cli from workspace
+└── README.md                # This file
 ```
 
+**Key Points:**
+- All documentation files are in `content/`
+- `content/package.json` is auto-created by `objectdocs init`
+- `content/.objectdocs/` is gitignored and not committed
+- Root directory remains clean
+
 ## 🚀 Getting Started
 
 ### Prerequisites
@@ -50,7 +57,7 @@ examples/starter/
 cd examples/starter
 ```
 
-2. Install dependencies:
+2. Install the CLI:
 
 ```bash
 pnpm install
@@ -65,14 +72,21 @@ pnpm objectdocs init
 ```
 
 This command will:
+- Create `content/package.json` with necessary scripts
 - Copy the `@objectdocs/site` engine to `content/.objectdocs`
-- Install necessary dependencies
+- Install dependencies in `content/.objectdocs/node_modules`
 - Prepare your project for development
 
 ### Development
 
 Start the development server:
 
+```bash
+cd content && npm run dev
+```
+
+Or if you have a root-level script configured:
+
 ```bash
 pnpm dev
 ```
@@ -83,16 +97,28 @@ The site will be available at [http://localhost:7777](http://localhost:7777).
 
 Build the project for production:
 
+```bash
+cd content && npm run build
+```
+
+Or with root-level script:
+
 ```bash
 pnpm build
 ```
 
-This will generate the production build in the `.next` directory.
+This will generate the production build in the `content/.objectdocs/.next` directory.
 
 ### Production Server
 
 Start the production server:
 
+```bash
+cd content && npm run start
+```
+
+Or with root-level script:
+
 ```bash
 pnpm start
 ```

examples/starter/package.json

@@ -4,9 +4,9 @@
   "private": true,
   "description": "Starter template for creating documentation sites with ObjectDocs",
   "scripts": {
-    "dev": "objectdocs dev",
-    "build": "objectdocs build",
-    "start": "objectdocs start"
+    "dev": "cd content && npm run dev",
+    "build": "cd content && npm run build",
+    "start": "cd content && npm run start"
   },
   "devDependencies": {
     "@objectdocs/cli": "workspace:*"

packages/cli/src/commands/init.mjs

@@ -22,7 +22,9 @@ export function registerInitCommand(cli) {
     .action(async (options) => {
       console.log('Initializing ObjectDocs...\n');
 
-      const targetDir = path.resolve(process.cwd(), 'content/.objectdocs');
+      const contentDir = path.resolve(process.cwd(), 'content');
+      const targetDir = path.resolve(contentDir, '.objectdocs');
+      const contentPackageJsonPath = path.resolve(contentDir, 'package.json');
 
       // Check if already initialized
       if (fs.existsSync(targetDir)) {
@@ -31,6 +33,12 @@ export function registerInitCommand(cli) {
         return;
       }
 
+      // Create content directory if it doesn't exist
+      if (!fs.existsSync(contentDir)) {
+        fs.mkdirSync(contentDir, { recursive: true });
+        console.log(`📁 Created content directory\n`);
+      }
+      
       // Resolve the site package directory
       let siteDir;
       try {
@@ -65,48 +73,96 @@ export function registerInitCommand(cli) {
 
       console.log('✅ ObjectDocs site copied successfully!\n');
 
+      // Initialize or update content/package.json
+      let packageJson = {};
+      if (fs.existsSync(contentPackageJsonPath)) {
+        console.log('📝 Updating existing content/package.json\n');
+        packageJson = JSON.parse(fs.readFileSync(contentPackageJsonPath, 'utf-8'));
+      } else {
+        console.log('📝 Creating content/package.json\n');
+        packageJson = {
+          name: 'objectdocs-content',
+          version: '0.1.0',
+          private: true,
+          description: 'ObjectDocs documentation content'
+        };
+      }
+      
+      // Ensure scripts section exists
+      if (!packageJson.scripts) {
+        packageJson.scripts = {};
+      }
+      
+      // Add/update ObjectDocs scripts
+      packageJson.scripts = {
+        ...packageJson.scripts,
+        dev: 'cd .objectdocs && npm run dev',
+        build: 'cd .objectdocs && npm run build',
+        start: 'cd .objectdocs && npm run start'
+      };
+      
+      // Write package.json
+      fs.writeFileSync(
+        contentPackageJsonPath,
+        JSON.stringify(packageJson, null, 2) + '\n'
+      );
+      
+      console.log('✅ content/package.json configured\n');
+      
       // Add to .gitignore
       const gitignorePath = path.resolve(process.cwd(), '.gitignore');
-      const gitignoreEntry = 'content/.objectdocs';
+      const gitignoreEntries = ['content/.objectdocs', 'content/node_modules'];
 
       try {
         let gitignoreContent = '';
         if (fs.existsSync(gitignorePath)) {
           gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
         }
 
-        // Check if the entry already exists (as a complete line)
         const lines = gitignoreContent.split('\n').map(line => line.trim());
-        if (!lines.includes(gitignoreEntry)) {
-          // Add the entry with a comment
+        const entriesToAdd = gitignoreEntries.filter(entry => !lines.includes(entry));
+        
+        if (entriesToAdd.length > 0) {
           const separator = gitignoreContent.trim() ? '\n\n' : '';
-          const newContent = `${gitignoreContent.trim()}${separator}# ObjectDocs\n${gitignoreEntry}\n`;
+          const newContent = `${gitignoreContent.trim()}${separator}# ObjectDocs\n${entriesToAdd.join('\n')}\n`;
           fs.writeFileSync(gitignorePath, newContent);
-          console.log('📝 Added content/.objectdocs to .gitignore\n');
+          console.log(`📝 Added ${entriesToAdd.join(', ')} to .gitignore\n`);
         }
       } catch (e) {
         console.warn('⚠️  Could not update .gitignore:', e.message);
       }
 
       // Install dependencies in the target directory
-      console.log('📦 Installing dependencies...\n');
+      console.log('📦 Installing dependencies in content/.objectdocs...\n');
 
       const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
       const installProcess = spawn(npmCmd, ['install', '--legacy-peer-deps'], {
         cwd: targetDir,
         stdio: 'inherit'
       });
 
-      installProcess.on('close', (code) => {
-        if (code === 0) {
-          console.log('\n✅ Dependencies installed successfully!');
-          console.log('\n🎉 ObjectDocs initialized! You can now run:');
-          console.log('   pnpm dev    - Start development server');
-          console.log('   pnpm build  - Build for production\n');
-        } else {
-          console.error('\n❌ Failed to install dependencies');
-          process.exit(code);
-        }
+      // Wait for the install process to complete
+      await new Promise((resolve, reject) => {
+        installProcess.on('close', (code) => {
+          if (code === 0) {
+            console.log('\n✅ Dependencies installed successfully!');
+            console.log('\n🎉 ObjectDocs initialized! You can now run:');
+            console.log('   cd content && npm run dev    - Start development server');
+            console.log('   cd content && npm run build  - Build for production\n');
+            console.log('Or if you have npm scripts in your root package.json:');
+            console.log('   npm run dev    - Start development server');
+            console.log('   npm run build  - Build for production\n');
+            resolve();
+          } else {
+            console.error('\n❌ Failed to install dependencies');
+            reject(new Error(`Install failed with code ${code}`));
+          }
+        });
+        
+        installProcess.on('error', (err) => {
+          console.error('\n❌ Failed to start install process:', err.message);
+          reject(err);
+        });
       });
     });
 }