chore(scripts): improve build scripts

Enhance build scripts for better maintainability:

- Update generate-metadata.mjs to read locales from i18n config
- Auto-generate articles.ts and docs.ts with component imports
- Improve sort-manifest-fields.mjs for consistent field ordering
- Add better error handling and logging

These improvements make the build process more robust and reduce
manual configuration when adding new content or languages.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ericyangpan

scripts/generate-metadata.mjs

@@ -14,6 +14,21 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const rootDir = path.join(__dirname, '..');
 
+// Read supported locales from i18n config
+function getSupportedLocales() {
+  const configPath = path.join(rootDir, 'src/i18n/config.ts');
+  const configContent = fs.readFileSync(configPath, 'utf8');
+  // Extract locales array from: export const locales = ['en', 'zh-Hans', 'de'] as const;
+  const match = configContent.match(/export const locales = \[([^\]]+)\]/);
+  if (!match) {
+    throw new Error('Could not find locales export in src/i18n/config.ts');
+  }
+  // Parse the array: "'en', 'zh-Hans', 'de'" -> ['en', 'zh-Hans', 'de']
+  return match[1].split(',').map(s => s.trim().replace(/['"]/g, ''));
+}
+
+const SUPPORTED_LOCALES = getSupportedLocales();
+
 function getMDXFiles(directory) {
   return fs.readdirSync(directory).filter(file => file.endsWith('.mdx'));
 }
@@ -28,11 +43,6 @@ function getSlugFromFilename(fileName) {
   return fileName.replace(/\.mdx$/, '');
 }
 
-function extractH1FromMDX(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : '';
-}
-
 // Parse FAQ sections from a unified index.mdx file
 // Each H1 heading becomes a FAQ item with its title and content
 function parseFaqSections(content) {
@@ -43,7 +53,6 @@ function parseFaqSections(content) {
   const sections = [];
   const h1Regex = /^# (.+)$/gm;
   let match;
-  let lastIndex = 0;
   const matches = [];
 
   // Find all H1 headings and their positions
@@ -106,7 +115,6 @@ function generateArticlesMetadataForLocale(locale) {
 
 // Generate articles metadata for all locales
 function generateArticlesMetadata() {
-  const SUPPORTED_LOCALES = ['en', 'zh-Hans'];
   const articlesMetadata = {};
 
   for (const locale of SUPPORTED_LOCALES) {
@@ -145,7 +153,6 @@ function generateDocsMetadataForLocale(locale) {
 
 // Generate docs metadata for all locales
 function generateDocsMetadata() {
-  const SUPPORTED_LOCALES = ['en', 'zh-Hans'];
   const docsMetadata = {};
 
   for (const locale of SUPPORTED_LOCALES) {
@@ -186,7 +193,6 @@ function generateFaqMetadataForLocale(locale) {
 
 // Generate FAQ metadata for all locales
 function generateFaqMetadata() {
-  const SUPPORTED_LOCALES = ['en', 'zh-Hans'];
   const faqMetadata = {};
 
   for (const locale of SUPPORTED_LOCALES) {
@@ -208,9 +214,6 @@ function generateStackCounts() {
     vendors: 'vendors',
   };
 
-  // Single files (old structure)
-  const singleFiles = {};
-
   const stackCounts = {};
 
   // Count files in directories
@@ -232,27 +235,45 @@ function generateStackCounts() {
     }
   }
 
-  // Count items in single files
-  for (const [stackId, fileName] of Object.entries(singleFiles)) {
-    const manifestPath = path.join(rootDir, 'manifests', fileName);
+  return stackCounts;
+}
 
-    if (!fs.existsSync(manifestPath)) {
-      console.warn(`⚠️  Manifest file not found: ${manifestPath}`);
-      stackCounts[stackId] = 0;
-      continue;
+// Generate component imports for articles
+function generateArticleComponentsCode(articles) {
+  const locales = Object.keys(articles);
+  const componentLines = [];
+
+  for (const locale of locales) {
+    const localeArticles = articles[locale];
+    const componentEntries = localeArticles.map(article =>
+      `    '${article.slug}': require('@content/articles/${locale}/${article.slug}.mdx').default,`
+    ).join('\n');
+
+    if (componentEntries) {
+      componentLines.push(`  '${locale}': {\n${componentEntries}\n  },`);
     }
+  }
 
-    try {
-      const fileContents = fs.readFileSync(manifestPath, 'utf8');
-      const manifestData = JSON.parse(fileContents);
-      stackCounts[stackId] = Array.isArray(manifestData) ? manifestData.length : 0;
-    } catch (error) {
-      console.error(`❌ Error reading ${fileName}:`, error.message);
-      stackCounts[stackId] = 0;
+  return `const articleComponents: Record<string, Record<string, React.ComponentType>> = {\n${componentLines.join('\n')}\n};`;
+}
+
+// Generate component imports for docs
+function generateDocComponentsCode(docs) {
+  const locales = Object.keys(docs);
+  const componentLines = [];
+
+  for (const locale of locales) {
+    const localeDocs = docs[locale];
+    const componentEntries = localeDocs.map(doc =>
+      `    '${doc.slug}': require('@content/docs/${locale}/${doc.slug}.mdx').default,`
+    ).join('\n');
+
+    if (componentEntries) {
+      componentLines.push(`  '${locale}': {\n${componentEntries}\n  },`);
     }
   }
 
-  return stackCounts;
+  return `const docComponents: Record<string, Record<string, React.ComponentType>> = {\n${componentLines.join('\n')}\n};`;
 }
 
 // Main execution
@@ -277,8 +298,8 @@ function main() {
   const content = `// This file is auto-generated by scripts/generate-metadata.mjs
 // DO NOT EDIT MANUALLY
 
-import type { ArticleMetadata } from '../articles';
-import type { DocSection } from '../docs';
+import type { ArticleMetadata } from './articles';
+import type { DocSection } from './docs';
 import type { CollectionSection } from '../collections';
 import type { FaqItem } from '../faq';
 
@@ -295,6 +316,85 @@ export const stackCounts: Record<string, number> = ${JSON.stringify(stackCounts,
 
   fs.writeFileSync(outputFile, content, 'utf8');
 
+  // Generate articles.ts file in generated directory
+  const articlesGeneratedFile = path.join(outputDir, 'articles.ts');
+  const articlesComponentsCode = generateArticleComponentsCode(articles);
+  const articlesGeneratedContent = `// This file is auto-generated by scripts/generate-metadata.mjs
+// DO NOT EDIT MANUALLY
+
+import { articlesMetadata } from './metadata';
+
+export type ArticleMetadata = {
+  title: string;
+  description: string;
+  date: string;
+  slug: string;
+};
+
+// Get articles for a specific locale with fallback to English
+export function getArticles(locale: string = 'en'): ArticleMetadata[] {
+  return articlesMetadata[locale] || articlesMetadata['en'] || [];
+}
+
+// Get all articles (backward compatibility)
+export const articles: ArticleMetadata[] = getArticles('en');
+
+// Get a specific article by slug for a given locale
+export function getArticleBySlug(slug: string, locale: string = 'en'): ArticleMetadata | undefined {
+  const localeArticles = getArticles(locale);
+  return localeArticles.find((article) => article.slug === slug);
+}
+
+// MDX components mapping for all locales (webpack will handle this at build time)
+${articlesComponentsCode}
+
+// Get components for a specific locale with fallback to English
+export function getArticleComponents(locale: string = 'en'): Record<string, React.ComponentType> {
+  return articleComponents[locale] || articleComponents['en'] || {};
+}
+`;
+
+  fs.writeFileSync(articlesGeneratedFile, articlesGeneratedContent, 'utf8');
+
+  // Generate docs.ts file in generated directory
+  const docsGeneratedFile = path.join(outputDir, 'docs.ts');
+  const docsComponentsCode = generateDocComponentsCode(docs);
+  const docsGeneratedContent = `// This file is auto-generated by scripts/generate-metadata.mjs
+// DO NOT EDIT MANUALLY
+
+import { docsMetadata } from './metadata';
+
+export type DocSection = {
+  id: string;
+  title: string;
+  slug: string;
+};
+
+// Get doc sections for a specific locale with fallback to English
+export function getDocSections(locale: string): DocSection[] {
+  return docsMetadata[locale] || docsMetadata['en'] || [];
+}
+
+// Get all doc sections (backward compatibility)
+export const docSections: DocSection[] = getDocSections('en');
+
+// Get a specific doc by slug for a given locale
+export function getDocBySlug(slug: string, locale: string = 'en'): DocSection | undefined {
+  const sections = getDocSections(locale);
+  return sections.find((doc) => doc.slug === slug);
+}
+
+// MDX components mapping for all locales (webpack will handle this at build time)
+${docsComponentsCode}
+
+// Get components for a specific locale with fallback to English
+export function getDocComponents(locale: string = 'en'): Record<string, React.ComponentType> {
+  return docComponents[locale] || docComponents['en'] || {};
+}
+`;
+
+  fs.writeFileSync(docsGeneratedFile, docsGeneratedContent, 'utf8');
+
   // Calculate total docs, articles, and faqs across all locales
   const totalDocs = Object.values(docs).reduce((sum, localeDocs) => sum + localeDocs.length, 0);
   const totalArticles = Object.values(articles).reduce((sum, localeArticles) => sum + localeArticles.length, 0);
@@ -307,7 +407,10 @@ export const stackCounts: Record<string, number> = ${JSON.stringify(stackCounts,
 
   console.log(`✅ Generated metadata for ${totalArticles} articles (${articlesLocalesCounts}), ${totalDocs} docs (${docsLocalesCounts}), ${totalFaqs} faqs (${faqsLocalesCounts}), and collections (${collectionsLocales})`);
   console.log(`✅ Generated stack counts: ${stackCountsSummary}`);
-  console.log(`📝 Output: ${outputFile}`);
+  console.log(`📝 Generated files:`);
+  console.log(`   - ${outputFile}`);
+  console.log(`   - ${articlesGeneratedFile}`);
+  console.log(`   - ${docsGeneratedFile}`);
 }
 
 main();