Skip to content

Commit 5c7b06d

Browse files
heskewheskew
committed
workflow updates and some post-migration prep
1 parent 275530b commit 5c7b06d

File tree

7 files changed

+257
-29
lines changed

7 files changed

+257
-29
lines changed

‎site/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
# Production
55
/build
66

7+
# Latest (/docs/) is a build time copy of the latest version
8+
/docs
9+
710
# Generated files
811
.docusaurus
912
.cache-loader

‎site/docusaurus.config.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,11 +86,9 @@ const config: Config = {
8686
versions: {
8787
'current': {
8888
label: 'Latest',
89-
path: '',
9089
},
9190
'4.6': {
92-
label: '4.6',
93-
banner: 'none',
91+
banner: 'none', // No banner for this version
9492
},
9593
},
9694
remarkPlugins: [[require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }]],

‎site/package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
"scripts": {
66
"docusaurus": "docusaurus",
77
"start": "docusaurus start",
8-
"build": "docusaurus build",
8+
"sync-latest": "node scripts/sync-latest-version.js",
9+
"build": "npm run sync-latest && docusaurus build",
10+
"version": "node scripts/cut-version.js",
911
"swizzle": "docusaurus swizzle",
1012
"deploy": "docusaurus deploy",
1113
"clear": "docusaurus clear",

‎site/scripts/convert-and-run.sh‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -32,20 +32,6 @@ if [ ! -d "$SITE_DIR/versioned_docs" ] || [ ! -f "$SITE_DIR/versions.json" ]; th
3232
fi
3333
fi
3434

35-
# Convert current docs (from main branch) to Docusaurus format
36-
# Only do this if we don't already have docs from the migration
37-
if [ ! -d "$SITE_DIR/docs" ] || [ -z "$(ls -A "$SITE_DIR/docs")" ]; then
38-
echo "Converting current docs to Docusaurus format..."
39-
node "$SCRIPT_DIR/convert-gitbook-to-docusaurus.js" "$REPO_ROOT/docs" "$SITE_DIR/docs"
40-
else
41-
echo "Docs already exist from version migration, skipping current branch conversion"
42-
fi
43-
44-
if [ $? -ne 0 ]; then
45-
echo "Conversion failed!"
46-
exit 1
47-
fi
48-
4935
# Run the appropriate Docusaurus command
5036
cd "$SITE_DIR"
5137
case "$COMMAND" in

‎site/scripts/cut-version.js‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* Script to cut a new version from the repository's /docs directory
5+
* This is used for creating new versions (4.7+) after the GitBook migration
6+
*
7+
* Usage: npm run version <version>
8+
* Example: npm run version 4.7
9+
*/
10+
11+
const fs = require('node:fs');
12+
const path = require('node:path');
13+
const { execSync } = require('node:child_process');
14+
15+
const SCRIPT_DIR = __dirname;
16+
const SITE_DIR = path.dirname(SCRIPT_DIR);
17+
const REPO_ROOT = path.dirname(SITE_DIR);
18+
const REPO_DOCS = path.join(REPO_ROOT, 'docs');
19+
const SITE_DOCS = path.join(SITE_DIR, 'docs');
20+
21+
function copyDirectory(src, dest) {
22+
// Create destination directory
23+
fs.mkdirSync(dest, { recursive: true });
24+
25+
// Read all items in source directory
26+
const items = fs.readdirSync(src, { withFileTypes: true });
27+
28+
for (const item of items) {
29+
const srcPath = path.join(src, item.name);
30+
const destPath = path.join(dest, item.name);
31+
32+
if (item.isDirectory()) {
33+
// Recursively copy subdirectories
34+
copyDirectory(srcPath, destPath);
35+
} else {
36+
// Copy file
37+
fs.copyFileSync(srcPath, destPath);
38+
}
39+
}
40+
}
41+
42+
function removeDirectory(dir) {
43+
if (fs.existsSync(dir)) {
44+
fs.rmSync(dir, { recursive: true, force: true });
45+
}
46+
}
47+
48+
function main() {
49+
const version = process.argv[2];
50+
51+
if (!version) {
52+
console.error('Usage: npm run version <version>');
53+
console.error('Example: npm run version 4.7');
54+
process.exit(1);
55+
}
56+
57+
// Validate version format
58+
if (!/^\d+\.\d+$/.test(version)) {
59+
console.error(`Error: Invalid version format "${version}". Expected format: X.Y (e.g., 4.7)`);
60+
process.exit(1);
61+
}
62+
63+
console.log(`\nCutting version ${version} from repository docs...`);
64+
65+
// Check if repo docs exist
66+
if (!fs.existsSync(REPO_DOCS)) {
67+
console.error(`Error: Repository docs not found at ${REPO_DOCS}`);
68+
console.error('After migration, the repository /docs directory should contain vNext documentation.');
69+
process.exit(1);
70+
}
71+
72+
// Remove existing site/docs if it exists (it's just a build-time copy)
73+
if (fs.existsSync(SITE_DOCS)) {
74+
console.log('Removing existing site/docs (build-time copy)...');
75+
removeDirectory(SITE_DOCS);
76+
}
77+
78+
try {
79+
// Copy repo docs to site docs
80+
console.log('Copying repository docs to site/docs...');
81+
copyDirectory(REPO_DOCS, SITE_DOCS);
82+
83+
// Run Docusaurus version command
84+
console.log(`\nRunning Docusaurus version command for ${version}...`);
85+
execSync(`npm run docusaurus docs:version ${version}`, {
86+
cwd: SITE_DIR,
87+
stdio: 'inherit'
88+
});
89+
90+
console.log(`\n✅ Successfully created version ${version}`);
91+
console.log(` - Versioned docs created at: versioned_docs/version-${version}/`);
92+
console.log(` - Version added to versions.json`);
93+
94+
// Clean up - remove the temporary site/docs (it's in .gitignore anyway)
95+
console.log('\nCleaning up temporary site/docs...');
96+
removeDirectory(SITE_DOCS);
97+
98+
console.log('\n🎉 Version creation complete!');
99+
console.log('\nNext steps:');
100+
console.log('1. Create a PR with the new versioned docs and updated versions.json');
101+
console.log('2. Site will deploy automatically when PR is merged');
102+
console.log(`\nNote: Version ${version} is now the latest and will be synced to site/docs during build`);
103+
104+
} catch (error) {
105+
console.error('\n❌ Error creating version:', error.message || error);
106+
107+
// Clean up on error
108+
if (fs.existsSync(SITE_DOCS)) {
109+
console.log('Cleaning up temporary site/docs...');
110+
removeDirectory(SITE_DOCS);
111+
}
112+
113+
process.exit(1);
114+
}
115+
}
116+
117+
main();

‎site/scripts/migrate-branches-to-versions.js‎

Lines changed: 41 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ function copyDirectory(src, dest, excludePaths = []) {
177177
}
178178

179179
// Process a single release branch
180-
function processBranch(branch, isLatest = false) {
180+
function processBranch(branch) {
181181
const version = branchToVersion(branch);
182182
console.log(`\n=== Processing ${branch} (version ${version}) ===`);
183183

@@ -249,14 +249,6 @@ function processBranch(branch, isLatest = false) {
249249
// Generate sidebar for this version
250250
generateVersionedSidebar(version, versionedPath);
251251

252-
// If this is the latest version, ALSO copy to main docs directory
253-
if (isLatest) {
254-
console.log('Also copying latest version to main docs directory...');
255-
const mainDocsPath = path.join(SITE_DIR, 'docs');
256-
fs.rmSync(mainDocsPath, { recursive: true, force: true });
257-
copyDirectory(outputPath, mainDocsPath);
258-
}
259-
260252
// Copy images to static directory with version prefix
261253
const versionedImagesPath = path.join(SITE_DIR, 'static', 'img', `v${version}`);
262254
if (fs.existsSync(path.join(tempVersionDir, 'images'))) {
@@ -556,10 +548,9 @@ async function migrate() {
556548
const versions = [];
557549
for (let i = 0; i < RELEASE_BRANCHES.length; i++) {
558550
const branch = RELEASE_BRANCHES[i];
559-
const isLatest = i === RELEASE_BRANCHES.length - 1;
560551

561552
try {
562-
const version = processBranch(branch, isLatest);
553+
const version = processBranch(branch);
563554
versions.push(version); // Add all versions, including the latest
564555
} catch (error) {
565556
console.error(`Failed to process ${branch}:`, error.message);
@@ -570,6 +561,45 @@ async function migrate() {
570561
// Generate versions.json
571562
generateVersionsJson(versions);
572563

564+
// Process main branch docs (current/vNext content) and convert them in-place
565+
console.log('\n=== Processing main branch docs (current/vNext) ===');
566+
console.log('Converting main branch /docs from GitBook to Docusaurus format (in-place)...');
567+
568+
if (fs.existsSync(DOCS_DIR)) {
569+
// Create temp directory for main branch conversion
570+
const tempMainDir = path.join(TEMP_DIR, 'main-branch');
571+
fs.mkdirSync(tempMainDir, { recursive: true });
572+
573+
// Copy main branch docs and images to temp
574+
copyDirectory(DOCS_DIR, path.join(tempMainDir, 'docs'));
575+
if (fs.existsSync(IMAGES_DIR)) {
576+
copyDirectory(IMAGES_DIR, path.join(tempMainDir, 'images'));
577+
}
578+
579+
// Set IMAGES_PATH for conversion
580+
const originalImagesPath = process.env.IMAGES_PATH;
581+
process.env.IMAGES_PATH = path.join(tempMainDir, 'images');
582+
583+
// Convert main branch docs
584+
const mainDocsInput = path.join(tempMainDir, 'docs');
585+
const mainDocsOutput = path.join(tempMainDir, 'converted-docs');
586+
convertGitBookToDocusaurus(mainDocsInput, mainDocsOutput, mainDocsInput, mainDocsOutput);
587+
588+
// Replace root /docs with converted version
589+
console.log('Replacing root /docs with converted Docusaurus format...');
590+
fs.rmSync(DOCS_DIR, { recursive: true, force: true });
591+
copyDirectory(mainDocsOutput, DOCS_DIR);
592+
593+
// Restore IMAGES_PATH
594+
if (originalImagesPath) {
595+
process.env.IMAGES_PATH = originalImagesPath;
596+
} else {
597+
delete process.env.IMAGES_PATH;
598+
}
599+
600+
console.log('✓ Main branch /docs converted to Docusaurus format (in-place)');
601+
}
602+
573603
// Clean up temp directory
574604
console.log('\nCleaning up temporary files...');
575605
fs.rmSync(TEMP_DIR, { recursive: true, force: true });

‎site/scripts/sync-latest-version.js‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* Sync the latest version to site/docs for 'current' documentation
5+
* This ensures '/' and '/<latest version>/' both work with the same content
6+
*/
7+
8+
const fs = require('node:fs');
9+
const path = require('node:path');
10+
11+
const SITE_DIR = path.join(__dirname, '..');
12+
const VERSIONED_DOCS_DIR = path.join(SITE_DIR, 'versioned_docs');
13+
const DOCS_DIR = path.join(SITE_DIR, 'docs');
14+
const VERSIONS_FILE = path.join(SITE_DIR, 'versions.json');
15+
16+
// Copy directory recursively
17+
// Why JavaScript instead of a shell command like `cp -r`?
18+
// 1. Cross-platform compatibility (Windows doesn't have cp)
19+
// 2. Better error handling and reporting
20+
// 3. Consistent with other build scripts in the project
21+
// While we could shell out to cp/robocopy based on platform,
22+
// keeping it in JS makes the build process more predictable
23+
function copyDirectory(src, dest) {
24+
if (!fs.existsSync(dest)) {
25+
fs.mkdirSync(dest, { recursive: true });
26+
}
27+
28+
const entries = fs.readdirSync(src, { withFileTypes: true });
29+
30+
for (const entry of entries) {
31+
const srcPath = path.join(src, entry.name);
32+
const destPath = path.join(dest, entry.name);
33+
34+
if (entry.isDirectory()) {
35+
copyDirectory(srcPath, destPath);
36+
} else {
37+
fs.copyFileSync(srcPath, destPath);
38+
}
39+
}
40+
}
41+
42+
function main() {
43+
// Read versions.json to get the latest version
44+
// Note: versions.json is a required Docusaurus file that defines:
45+
// - Which versions exist and their order
46+
// - Which version appears in the version dropdown
47+
// - The ordering for version navigation
48+
// We use it here as the source of truth since Docusaurus requires it anyway
49+
50+
if (!fs.existsSync(VERSIONS_FILE)) {
51+
console.error(`Error: versions.json not found at ${VERSIONS_FILE}`);
52+
console.error('Run the migration script first to create versioned docs.');
53+
process.exit(1);
54+
}
55+
56+
const versions = JSON.parse(fs.readFileSync(VERSIONS_FILE, 'utf8'));
57+
const latestVersion = versions[0]; // First version in the array is the latest
58+
59+
if (!latestVersion) {
60+
console.error('Error: No versions found in versions.json');
61+
process.exit(1);
62+
}
63+
64+
const versionedDocsPath = path.join(VERSIONED_DOCS_DIR, `version-${latestVersion}`);
65+
66+
if (!fs.existsSync(versionedDocsPath)) {
67+
console.error(`Error: Version ${latestVersion} docs not found at ${versionedDocsPath}`);
68+
console.error('Run the migration script first to create versioned docs.');
69+
process.exit(1);
70+
}
71+
72+
console.log(`Syncing version ${latestVersion} to site/docs for 'current'...`);
73+
74+
// Remove existing docs directory
75+
if (fs.existsSync(DOCS_DIR)) {
76+
fs.rmSync(DOCS_DIR, { recursive: true, force: true });
77+
}
78+
79+
// Copy versioned docs to site/docs
80+
copyDirectory(versionedDocsPath, DOCS_DIR);
81+
82+
console.log(`✓ Version ${latestVersion} synced to site/docs`);
83+
console.log(` - Available at / as 'current'`);
84+
console.log(` - Also available at /${latestVersion}/ for version-specific permalinking`);
85+
}
86+
87+
// Run if called directly
88+
if (require.main === module) {
89+
main();
90+
}
91+
92+
module.exports = { main };

0 commit comments

Comments
 (0)