fix(docs): sync Governance section generation with webpack.js.org content model

Author: Jatinyadav29

src/utilities/fetch-governance.mjs

@@ -12,10 +12,10 @@ const __dirname = path.dirname(__filename);
 const owner = 'webpack';
 const repo = 'governance';
 
-// Local output directory inside webpack.js.org
-const outputDir = path.resolve(__dirname, '../content/contribute/governance');
+// Output directory for governance content
+const outputDir = path.resolve(__dirname, '../content/contribute/Governance');
 
-// Map source files to destination filenames
+// Mapping GitHub files to local filenames
 const fileMap = {
   'README.md': 'index.mdx',
   'CHARTER.md': 'charter.mdx',
@@ -24,9 +24,9 @@ const fileMap = {
   'WORKING_GROUPS.md': 'working-groups.mdx',
 };
 
-// Generate frontmatter titles automatically
+// Generate title for frontmatter
 function generateTitle(filename) {
-  if (filename === 'README.md') return 'Governance Overview';
+  if (filename === 'README.md') return 'Governance';
   return filename
     .replace('.md', '')
     .replace(/_/g, ' ')
@@ -35,61 +35,45 @@ function generateTitle(filename) {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-// --- Helpers for index link generation ---
-
+// Helper to get slug from filename
 function destSlugFromFilename(destFile) {
   const name = path.basename(destFile, path.extname(destFile));
-  if (name.toLowerCase() === 'index') return '/';
-  return `/${name}/`;
+  return name.toLowerCase() === 'index' ? '/' : `/${name}/`;
 }
 
+// Replace related section block in index
 function replaceRelatedSection(indexContent, relatedBlock) {
   const startMarker = '{/* GOV-RELATED-START */}';
   const endMarker = '{/* GOV-RELATED-END */}';
   const regex = new RegExp(`${startMarker}[\\s\\S]*?${endMarker}`, 'm');
   const wrappedBlock = `${startMarker}\n${relatedBlock}\n${endMarker}`;
-
-  if (regex.test(indexContent)) {
-    return indexContent.replace(regex, wrappedBlock);
-  } else {
-    return `${indexContent}\n\n${wrappedBlock}\n`;
-  }
+  return regex.test(indexContent)
+    ? indexContent.replace(regex, wrappedBlock)
+    : `${indexContent}\n\n${wrappedBlock}\n`;
 }
 
 async function fetchGovernanceDocs() {
-  console.log(
-    'Fetching governance markdown files from webpack/governance...\n'
-  );
+  console.log('Fetching governance markdown files from webpack/governance...');
 
   await mkdirp(outputDir);
 
   try {
-    // Get list of files in the governance repo
     const { data: files } = await api.repos.getContent({
       owner,
       repo,
       path: '',
     });
-
-    // Filter markdown files
     const markdownFiles = files.filter((file) => file.name.endsWith('.md'));
 
     for (const file of markdownFiles) {
       const filename = file.name;
       const destFile = fileMap[filename];
+      if (!destFile) continue;
 
-      if (!destFile) {
-        console.log(`Skipping ${filename} — not mapped`);
-        continue;
-      }
-
-      const rawUrl = file.download_url;
-      const response = await fetch(rawUrl);
+      const response = await fetch(file.download_url);
       const content = await response.text();
-      // Add YAML frontmatter for better sidebar integration
       const title = generateTitle(filename);
 
-      // Optional ordering logic for sidebar
       const sortOrder =
         {
           'README.md': 0,
@@ -99,57 +83,61 @@ async function fetchGovernanceDocs() {
           'WORKING_GROUPS.md': 4,
         }[filename] ?? 10;
 
-      const frontmatter = yamlHeadmatter({
+      // Build frontmatter object: only add group for the index (README.md)
+      const fm = {
         title,
-        group: 'Governance',
         sort: sortOrder,
         source: `https://github.com/${owner}/${repo}/blob/main/${filename}`,
         edit: `https://github.com/${owner}/${repo}/edit/main/${filename}`,
-      });
-
-      const finalContent = frontmatter + content;
+      };
 
-      const destPath = path.join(outputDir, destFile);
-      await writeFile(destPath, finalContent, 'utf8');
+      if (filename === 'README.md') fm.group = 'Contribute';
 
-      console.log(
-        `Synced: ${filename} → ${path.relative(process.cwd(), destPath)}`
+      const frontmatter = yamlHeadmatter(fm);
+      await writeFile(
+        path.join(outputDir, destFile),
+        frontmatter + content,
+        'utf8'
       );
+      console.log(`Synced: ${filename}`);
     }
 
-    // After all files are written: update index with related document links
+    // Ensure index.mdx exists and is properly formatted
+    const indexPath = path.resolve(outputDir, 'index.mdx');
+    let indexContent = '';
+
     try {
-      const indexPath = path.resolve(outputDir, 'index.mdx');
-      let indexContent = '';
-
-      try {
-        indexContent = fs.readFileSync(indexPath, 'utf8');
-      } catch (err) {
-        indexContent =
-          '---\ntitle: Governance Overview\n---\n\n# Governance Overview\n\n';
-        console.log(err);
-      }
-
-      const relatedItems = Object.entries(fileMap)
-        .filter(([key]) => key !== 'README.md')
-        .map(([key, dest]) => {
-          const title = generateTitle(key);
-          const slug = destSlugFromFilename(dest);
-          const url = `/contribute/governance${slug}`;
-          return `- [${title}](${url})`;
-        })
-        .join('\n');
-
-      const relatedBlock = `## Related Documents\n\n${relatedItems}\n`;
-      const newIndex = replaceRelatedSection(indexContent, relatedBlock);
-
-      fs.writeFileSync(indexPath, newIndex, 'utf8');
-      console.log('Updated index.mdx with related governance links.');
-    } catch (err) {
-      console.error('Failed to update index links:', err);
+      indexContent = fs.readFileSync(indexPath, 'utf8');
+    } catch {
+      indexContent =
+        '---\n' +
+        'title: Governance\n' +
+        'group: Contribute\n' +
+        'directory: true\n' +
+        'sort: 0\n' +
+        '---\n\n' +
+        '# Governance\n\n';
+      console.log('Created fallback index.mdx with metadata.');
     }
 
-    console.log('\nGovernance content successfully synced!');
+    const relatedItems = Object.entries(fileMap)
+      .filter(([key]) => key !== 'README.md')
+      .map(([key, dest]) => {
+        const title = generateTitle(key);
+        const slug = destSlugFromFilename(dest);
+        return `- [${title}](/contribute/Governance${slug})`;
+      })
+      .join('\n');
+
+    const relatedBlock = `## Related Documents\n\n${relatedItems}\n`;
+    fs.writeFileSync(
+      indexPath,
+      replaceRelatedSection(indexContent, relatedBlock),
+      'utf8'
+    );
+    console.log('Updated index.mdx with related governance links.');
+
+    console.log('Governance content successfully synced.');
   } catch (error) {
     console.error('Error fetching governance files:', error.message);
     process.exitCode = 1;