refactor: improve readability and reduce logging in generate-llms-txt plugin

Author: satya164

docusaurus.config.ts

@@ -9,12 +9,13 @@ import remarkRawMarkdown from './src/plugins/remark-raw-markdown.mjs';
 import darkTheme from './src/themes/react-navigation-dark';
 import lightTheme from './src/themes/react-navigation-light';
 
+const url = 'https://reactnavigation.org';
 const latestVersion = '7.x';
 
 const config: Config = {
   title: 'React Navigation',
   tagline: 'Routing and navigation for your React Native apps',
-  url: 'https://reactnavigation.org/',
+  url,
   baseUrl: '/',
   favicon: 'img/favicon.ico',
   organizationName: 'react-navigation',
@@ -133,10 +134,7 @@ const config: Config = {
   plugins: [
     './src/plugins/disable-fully-specified.mjs',
     './src/plugins/react-navigation-versions.mjs',
-    [
-      './src/plugins/generate-llms-txt.mjs',
-      { latestVersion, baseUrl: 'https://reactnavigation.org' },
-    ],
+    ['./src/plugins/llms-txt.mjs', { latestVersion, baseUrl: url }],
     [
       '@docusaurus/plugin-client-redirects',
       {

src/plugins/generate-llms-txt.mjs src/plugins/llms-txt.mjssrc/plugins/generate-llms-txt.mjs renamed to src/plugins/llms-txt.mjs

@@ -1,6 +1,15 @@
-import fs from 'fs';
-import path from 'path';
-
+import fs from 'node:fs';
+import path from 'node:path';
+import util from 'node:util';
+import versions from '../../versions.json';
+
+/**
+ * Parses frontmatter from markdown content.
+ * Extracts metadata like title and description, and returns the cleaned content.
+ *
+ * @param {string} fileContent - Raw markdown file content.
+ * @returns {{data: Object, content: string}} - Parsed data and stripped content.
+ */
 function parseFrontMatter(fileContent) {
   const frontMatterRegex = /^---\n([\s\S]+?)\n---\n/;
   const match = fileContent.match(frontMatterRegex);
@@ -13,24 +22,42 @@ function parseFrontMatter(fileContent) {
   const content = fileContent.replace(frontMatterRegex, '');
 
   const data = {};
+
   frontMatterBlock.split('\n').forEach((line) => {
     const parts = line.split(':');
+
     if (parts.length >= 2) {
       const key = parts[0].trim();
+
       let value = parts.slice(1).join(':').trim();
+
+      // Remove surrounding quotes if present
       if (
-        (value.startsWith("'" ) && value.endsWith("'")) ||
+        (value.startsWith("'") && value.endsWith("'")) ||
         (value.startsWith('"') && value.endsWith('"'))
       ) {
         value = value.slice(1, -1);
       }
+
       data[key] = value;
     }
   });
 
   return { data, content };
 }
 
+/**
+ * Recursively processes sidebar items to generate the LLM index and collect full docs.
+ * Handles different sidebar structures (flat arrays, categories).
+ *
+ * @param {Array} items - Sidebar items to process.
+ * @param {string} docsPath - Base path to documentation files.
+ * @param {string} version - Current version being processed (e.g., '7.x').
+ * @param {boolean} isLatest - Whether this is the latest/stable version.
+ * @param {string} baseUrl - The base URL of the website.
+ * @param {number} level - Current nesting level for headings.
+ * @returns {{content: string, docs: Array}} - Generated index content and list of doc objects.
+ */
 function processSidebar(
   items,
   docsPath,
@@ -43,6 +70,7 @@ function processSidebar(
   let fullDocsList = [];
 
   items.forEach((item) => {
+    // Case 1: Item is a direct link (string ID)
     if (typeof item === 'string') {
       const id = item;
       const filePath = path.join(docsPath, `${id}.md`);
@@ -54,13 +82,9 @@ function processSidebar(
         const title = data.title || id;
         const description = data.description || '';
 
-        let urlPath;
-        if (isLatest) {
-          urlPath = `/docs/${id}`;
-        } else {
-          urlPath = `/docs/${version}/${id}`;
-        }
-
+        // Construct the public URL for the document
+        // Latest version uses /docs/id, others use /docs/version/id
+        const urlPath = isLatest ? `/docs/${id}` : `/docs/${version}/${id}`;
         const fullUrl = `${baseUrl}${urlPath}`;
 
         llmsContent += `- [${title}](${fullUrl})${
@@ -73,9 +97,12 @@ function processSidebar(
           content,
         });
       }
-    } else if (item.type === 'category') {
+    }
+    // Case 2: Item is a category object
+    else if (item.type === 'category') {
       const label = item.label;
-      const headingPrefix = '#'.repeat(level + 3);
+      const headingPrefix = '#'.repeat(level + 3); // Start at level 3 (###)
+
       llmsContent += `\n${headingPrefix} ${label}\n\n`;
 
       const { content: childContent, docs: childDocs } = processSidebar(
@@ -86,6 +113,7 @@ function processSidebar(
         baseUrl,
         level + 1
       );
+
       llmsContent += childContent;
       fullDocsList = fullDocsList.concat(childDocs);
     }
@@ -94,6 +122,11 @@ function processSidebar(
   return { content: llmsContent, docs: fullDocsList };
 }
 
+/**
+ * Generates the llms.txt and llms-full.txt files for a specific version.
+ *
+ * @returns {Array<string>} - List of generated filenames.
+ */
 function generateForVersion(
   siteDir,
   outDir,
@@ -102,8 +135,6 @@ function generateForVersion(
   isLatest,
   baseUrl
 ) {
-  console.log(`[generate-llms-txt] Generating for version ${version}...`);
-
   const docsPath = path.join(siteDir, 'versioned_docs', `version-${version}`);
   const sidebarPath = path.join(
     siteDir,
@@ -112,24 +143,27 @@ function generateForVersion(
   );
 
   if (!fs.existsSync(sidebarPath)) {
-    console.warn(
-      `[generate-llms-txt] Sidebar not found: ${sidebarPath}, skipping.`
-    );
-    return;
+    // Silent return if sidebar is missing to avoid noise
+    return [];
   }
 
   const sidebarConfig = JSON.parse(fs.readFileSync(sidebarPath, 'utf8'));
+
+  // Handle different Docusaurus sidebar structures (root 'docs' key or first key)
   let rootItems = sidebarConfig.docs || Object.values(sidebarConfig)[0] || [];
 
+  // Normalize object-style sidebars (older Docusaurus versions) to array format
   if (!Array.isArray(rootItems) && typeof rootItems === 'object') {
     const normalized = [];
+
     for (const [label, items] of Object.entries(rootItems)) {
       normalized.push({
         type: 'category',
         label: label,
         items: items,
       });
     }
+
     rootItems = normalized;
   }
 
@@ -141,12 +175,18 @@ function generateForVersion(
     baseUrl
   );
 
+  // 1. Generate Summary (llms.txt)
   let llmsTxt = `# React Navigation ${version}\n\n`;
+
   llmsTxt += `> Routing and navigation for your React Native apps.\n\n`;
   llmsTxt += `## Documentation\n`;
-
   llmsTxt += sidebarContent;
 
+  const summaryFilename = `${outputPrefix}.txt`;
+
+  fs.writeFileSync(path.join(outDir, summaryFilename), llmsTxt);
+
+  // 2. Generate Full Content (llms-full.txt)
   let llmsFullTxt = `# React Navigation ${version} Documentation\n\n`;
 
   docs.forEach((doc) => {
@@ -155,9 +195,9 @@ function generateForVersion(
     llmsFullTxt += `${doc.content.trim()}\n\n---\n\n`;
   });
 
-  const summaryFilename = `${outputPrefix}.txt`;
-
+  // Determine full filename (e.g., llms-v8.x -> llms-full-v8.x.txt)
   let fullFilename;
+
   if (outputPrefix === 'llms') {
     fullFilename = 'llms-full.txt';
   } else {
@@ -168,55 +208,47 @@ function generateForVersion(
     }
   }
 
-  fs.writeFileSync(path.join(outDir, summaryFilename), llmsTxt);
-  console.log(`[generate-llms-txt] Wrote ${summaryFilename}`);
-
   fs.writeFileSync(path.join(outDir, fullFilename), llmsFullTxt);
-  console.log(`[generate-llms-txt] Wrote ${fullFilename}`);
+
+  return [summaryFilename, fullFilename];
 }
 
 export default function (context, options) {
   return {
-    name: 'generate-llms-txt',
+    name: 'llms.txt',
     async postBuild({ siteDir, outDir }) {
       const { latestVersion, baseUrl } = options;
 
       if (!latestVersion) {
-        throw new Error(
-          '[generate-llms-txt] "latestVersion" option is required.'
-        );
-      }
-      if (!baseUrl) {
-        throw new Error('[generate-llms-txt] "baseUrl" option is required.');
+        throw new Error('[llms.txt] "latestVersion" option is required.');
       }
 
-      const versionsPath = path.join(siteDir, 'versions.json');
-      let versions = [];
-      if (fs.existsSync(versionsPath)) {
-        versions = JSON.parse(fs.readFileSync(versionsPath, 'utf8'));
-      } else {
-        console.warn(
-          '[generate-llms-txt] versions.json not found. Generating only for latestVersion.'
-        );
-        versions = [latestVersion];
+      if (!baseUrl) {
+        throw new Error('[llms.txt] "baseUrl" option is required.');
       }
 
-      console.log(`[generate-llms-txt] Found versions: ${versions.join(', ')}`);
-      console.log(`[generate-llms-txt] Latest version: ${latestVersion}`);
+      const generatedFiles = [];
 
       versions.forEach((version) => {
         const isLatest = version === latestVersion;
+        // Prefix: 'llms' for latest, 'llms-vX.x' for others
         const outputPrefix = isLatest ? 'llms' : `llms-v${version}`;
 
-        generateForVersion(
+        const files = generateForVersion(
           siteDir,
           outDir,
           version,
           outputPrefix,
           isLatest,
           baseUrl
         );
+
+        generatedFiles.push(...files);
       });
+
+      console.log(
+        `${util.styleText(['magenta', 'bold'], '[llms.txt]')} Wrote ${generatedFiles.length} files in build output.`
+      );
     },
   };
 }