Skip to content

Commit a92030d

Browse files
hotlonghotlong
authored
Merge pull request #32 from objectstack-ai/copilot/initialize-package-json-in-content
2 parents a5788c2 + 2219503 commit a92030d

6 files changed

Lines changed: 177 additions & 88 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -55,56 +55,28 @@ This architecture allows developers and technical writers to manage complex, mul
5555

5656
## 🚀 Quick Start
5757

58-
### 1. Create a new project
58+
### Option 1: In Any Existing Project (Recommended)
5959

60-
Initialize your documentation site structure:
60+
Initialize ObjectDocs in any existing GitHub project without polluting the root directory:
6161

6262
```bash
63-
mkdir my-docs
64-
cd my-docs
65-
pnpm init
66-
pnpm add -D @objectdocs/cli
67-
```
68-
69-
### 2. Configure scripts
70-
71-
Add the following scripts to your `package.json`:
72-
73-
```json
74-
{
75-
"scripts": {
76-
"dev": "objectdocs dev",
77-
"build": "objectdocs build",
78-
"start": "objectdocs start"
79-
}
80-
}
81-
```
82-
83-
### 3. Initialize ObjectDocs
84-
85-
Run the init command to set up the site engine:
86-
87-
```bash
88-
pnpm objectdocs init
63+
cd your-existing-project
64+
npx @objectdocs/cli init
8965
```
9066

9167
This will:
68+
- Create `content/package.json` with necessary scripts
9269
- Copy the site engine to `content/.objectdocs`
93-
- Install necessary dependencies
94-
- Automatically add `content/.objectdocs` to `.gitignore`
95-
- Prepare your project for development
96-
97-
### 4. Add content
70+
- Install dependencies in `content/.objectdocs/node_modules`
71+
- Automatically add `content/.objectdocs` and `content/node_modules` to `.gitignore`
72+
- Keep your project root clean and unpolluted
9873

99-
Create the basic directory structure:
74+
Then add content and start the server:
10075

10176
```bash
10277
mkdir -p content/docs
103-
```
104-
105-
Create `content/docs/index.mdx`:
10678

107-
```mdx
79+
cat > content/docs/index.mdx << 'EOF'
10880
---
10981
title: Welcome
11082
description: My new docs site
@@ -113,40 +85,76 @@ description: My new docs site
11385
# Hello World
11486
11587
Welcome to ObjectDocs!
88+
EOF
89+
90+
cat > content/docs/meta.json << 'EOF'
91+
{
92+
"pages": ["index"]
93+
}
94+
EOF
95+
96+
# Start the development server
97+
cd content && npm run dev
11698
```
11799

118-
Create `content/docs/meta.json`:
100+
Visit http://localhost:7777 to see your site.
101+
102+
### Option 2: New Standalone Project
103+
104+
For a new dedicated documentation project:
105+
106+
```bash
107+
mkdir my-docs
108+
cd my-docs
109+
npm init -y
110+
npm install -D @objectdocs/cli
111+
```
112+
113+
Add scripts to your root `package.json`:
119114

120115
```json
121116
{
122-
"pages": ["index"]
117+
"scripts": {
118+
"dev": "cd content && npm run dev",
119+
"build": "cd content && npm run build",
120+
"start": "cd content && npm run start"
121+
}
123122
}
124123
```
125124

126-
### 5. Start the server
125+
Initialize ObjectDocs:
127126

128127
```bash
129-
pnpm dev
128+
npm run init
129+
# or
130+
npx objectdocs init
130131
```
131132

132-
Visit http://localhost:7777 to see your site.
133+
Then follow the same steps as Option 1 to add content.
133134

134135
## 🏗️ Project Structure
135136

136137
ObjectDocs enforces a clear directory structure to ensure maintainability at scale:
137138

138139
```text
139140
.
140-
├── content/ # [Data Layer] Raw Content
141-
│ ├── .objectdocs/ # Site engine (auto-generated by init)
141+
├── content/ # [Data Layer] All documentation files
142+
│ ├── package.json # npm scripts (dev, build, start)
143+
│ ├── .objectdocs/ # Site engine (auto-generated, gitignored)
142144
│ ├── docs.site.json # Global settings (Nav, Logo, Branding)
143145
│ └── docs/
144146
│ ├── meta.json # Directory structure & sorting control
145147
│ └── index.mdx # Documentation content
146-
├── package.json
148+
├── package.json # (Optional) Root project package.json
147149
└── ...
148150
```
149151

152+
**Key Points:**
153+
- All documentation-related files are in `content/`
154+
- `content/.objectdocs/` is auto-generated and gitignored
155+
- Your project root remains clean
156+
- Perfect for adding docs to any existing project
157+
150158
## ⚙️ Configuration
151159

152160
ObjectDocs is designed to be "Configuration as Code".

‎examples/starter/README.md‎

Lines changed: 36 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,18 +23,25 @@ This starter template serves multiple purposes:
2323
```
2424
examples/starter/
2525
├── content/
26-
│ ├── .objectdocs/ # Site engine (created by init command)
27-
│ ├── docs.site.json # Global site configuration
26+
│ ├── package.json # npm scripts (auto-created by init)
27+
│ ├── .objectdocs/ # Site engine (created by init command, gitignored)
28+
│ ├── docs.site.json # Global site configuration
2829
│ └── docs/
29-
│ ├── meta.json # Sidebar navigation structure
30-
│ ├── index.mdx # Home page
30+
│ ├── meta.json # Sidebar navigation structure
31+
│ ├── index.mdx # Home page
3132
│ ├── getting-started.mdx
3233
│ └── configuration.mdx
33-
├── public/ # Static assets (logos, images)
34-
├── package.json # Uses @objectdocs/cli from workspace
35-
└── README.md # This file
34+
├── public/ # Static assets (logos, images)
35+
├── package.json # Uses @objectdocs/cli from workspace
36+
└── README.md # This file
3637
```
3738

39+
**Key Points:**
40+
- All documentation files are in `content/`
41+
- `content/package.json` is auto-created by `objectdocs init`
42+
- `content/.objectdocs/` is gitignored and not committed
43+
- Root directory remains clean
44+
3845
## 🚀 Getting Started
3946

4047
### Prerequisites
@@ -50,7 +57,7 @@ examples/starter/
5057
cd examples/starter
5158
```
5259

53-
2. Install dependencies:
60+
2. Install the CLI:
5461

5562
```bash
5663
pnpm install
@@ -65,14 +72,21 @@ pnpm objectdocs init
6572
```
6673

6774
This command will:
75+
- Create `content/package.json` with necessary scripts
6876
- Copy the `@objectdocs/site` engine to `content/.objectdocs`
69-
- Install necessary dependencies
77+
- Install dependencies in `content/.objectdocs/node_modules`
7078
- Prepare your project for development
7179

7280
### Development
7381

7482
Start the development server:
7583

84+
```bash
85+
cd content && npm run dev
86+
```
87+
88+
Or if you have a root-level script configured:
89+
7690
```bash
7791
pnpm dev
7892
```
@@ -83,16 +97,28 @@ The site will be available at [http://localhost:7777](http://localhost:7777).
8397

8498
Build the project for production:
8599

100+
```bash
101+
cd content && npm run build
102+
```
103+
104+
Or with root-level script:
105+
86106
```bash
87107
pnpm build
88108
```
89109

90-
This will generate the production build in the `.next` directory.
110+
This will generate the production build in the `content/.objectdocs/.next` directory.
91111

92112
### Production Server
93113

94114
Start the production server:
95115

116+
```bash
117+
cd content && npm run start
118+
```
119+
120+
Or with root-level script:
121+
96122
```bash
97123
pnpm start
98124
```

‎examples/starter/package.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44
"private": true,
55
"description": "Starter template for creating documentation sites with ObjectDocs",
66
"scripts": {
7-
"dev": "objectdocs dev",
8-
"build": "objectdocs build",
9-
"start": "objectdocs start"
7+
"dev": "cd content && npm run dev",
8+
"build": "cd content && npm run build",
9+
"start": "cd content && npm run start"
1010
},
1111
"devDependencies": {
1212
"@objectdocs/cli": "workspace:*"

‎packages/cli/src/commands/init.mjs‎

Lines changed: 74 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ export function registerInitCommand(cli) {
2222
.action(async (options) => {
2323
console.log('Initializing ObjectDocs...\n');
2424

25-
const targetDir = path.resolve(process.cwd(), 'content/.objectdocs');
25+
const contentDir = path.resolve(process.cwd(), 'content');
26+
const targetDir = path.resolve(contentDir, '.objectdocs');
27+
const contentPackageJsonPath = path.resolve(contentDir, 'package.json');
2628

2729
// Check if already initialized
2830
if (fs.existsSync(targetDir)) {
@@ -31,6 +33,12 @@ export function registerInitCommand(cli) {
3133
return;
3234
}
3335

36+
// Create content directory if it doesn't exist
37+
if (!fs.existsSync(contentDir)) {
38+
fs.mkdirSync(contentDir, { recursive: true });
39+
console.log(`📁 Created content directory\n`);
40+
}
41+
3442
// Resolve the site package directory
3543
let siteDir;
3644
try {
@@ -65,48 +73,96 @@ export function registerInitCommand(cli) {
6573

6674
console.log('✅ ObjectDocs site copied successfully!\n');
6775

76+
// Initialize or update content/package.json
77+
let packageJson = {};
78+
if (fs.existsSync(contentPackageJsonPath)) {
79+
console.log('📝 Updating existing content/package.json\n');
80+
packageJson = JSON.parse(fs.readFileSync(contentPackageJsonPath, 'utf-8'));
81+
} else {
82+
console.log('📝 Creating content/package.json\n');
83+
packageJson = {
84+
name: 'objectdocs-content',
85+
version: '0.1.0',
86+
private: true,
87+
description: 'ObjectDocs documentation content'
88+
};
89+
}
90+
91+
// Ensure scripts section exists
92+
if (!packageJson.scripts) {
93+
packageJson.scripts = {};
94+
}
95+
96+
// Add/update ObjectDocs scripts
97+
packageJson.scripts = {
98+
...packageJson.scripts,
99+
dev: 'cd .objectdocs && npm run dev',
100+
build: 'cd .objectdocs && npm run build',
101+
start: 'cd .objectdocs && npm run start'
102+
};
103+
104+
// Write package.json
105+
fs.writeFileSync(
106+
contentPackageJsonPath,
107+
JSON.stringify(packageJson, null, 2) + '\n'
108+
);
109+
110+
console.log('✅ content/package.json configured\n');
111+
68112
// Add to .gitignore
69113
const gitignorePath = path.resolve(process.cwd(), '.gitignore');
70-
const gitignoreEntry = 'content/.objectdocs';
114+
const gitignoreEntries = ['content/.objectdocs', 'content/node_modules'];
71115

72116
try {
73117
let gitignoreContent = '';
74118
if (fs.existsSync(gitignorePath)) {
75119
gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
76120
}
77121

78-
// Check if the entry already exists (as a complete line)
79122
const lines = gitignoreContent.split('\n').map(line => line.trim());
80-
if (!lines.includes(gitignoreEntry)) {
81-
// Add the entry with a comment
123+
const entriesToAdd = gitignoreEntries.filter(entry => !lines.includes(entry));
124+
125+
if (entriesToAdd.length > 0) {
82126
const separator = gitignoreContent.trim() ? '\n\n' : '';
83-
const newContent = `${gitignoreContent.trim()}${separator}# ObjectDocs\n${gitignoreEntry}\n`;
127+
const newContent = `${gitignoreContent.trim()}${separator}# ObjectDocs\n${entriesToAdd.join('\n')}\n`;
84128
fs.writeFileSync(gitignorePath, newContent);
85-
console.log('📝 Added content/.objectdocs to .gitignore\n');
129+
console.log(`📝 Added ${entriesToAdd.join(', ')} to .gitignore\n`);
86130
}
87131
} catch (e) {
88132
console.warn('⚠️ Could not update .gitignore:', e.message);
89133
}
90134

91135
// Install dependencies in the target directory
92-
console.log('📦 Installing dependencies...\n');
136+
console.log('📦 Installing dependencies in content/.objectdocs...\n');
93137

94138
const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
95139
const installProcess = spawn(npmCmd, ['install', '--legacy-peer-deps'], {
96140
cwd: targetDir,
97141
stdio: 'inherit'
98142
});
99143

100-
installProcess.on('close', (code) => {
101-
if (code === 0) {
102-
console.log('\n✅ Dependencies installed successfully!');
103-
console.log('\n🎉 ObjectDocs initialized! You can now run:');
104-
console.log(' pnpm dev - Start development server');
105-
console.log(' pnpm build - Build for production\n');
106-
} else {
107-
console.error('\n❌ Failed to install dependencies');
108-
process.exit(code);
109-
}
144+
// Wait for the install process to complete
145+
await new Promise((resolve, reject) => {
146+
installProcess.on('close', (code) => {
147+
if (code === 0) {
148+
console.log('\n✅ Dependencies installed successfully!');
149+
console.log('\n🎉 ObjectDocs initialized! You can now run:');
150+
console.log(' cd content && npm run dev - Start development server');
151+
console.log(' cd content && npm run build - Build for production\n');
152+
console.log('Or if you have npm scripts in your root package.json:');
153+
console.log(' npm run dev - Start development server');
154+
console.log(' npm run build - Build for production\n');
155+
resolve();
156+
} else {
157+
console.error('\n❌ Failed to install dependencies');
158+
reject(new Error(`Install failed with code ${code}`));
159+
}
160+
});
161+
162+
installProcess.on('error', (err) => {
163+
console.error('\n❌ Failed to start install process:', err.message);
164+
reject(err);
165+
});
110166
});
111167
});
112168
}

0 commit comments

Comments
 (0)