From d8fc7746e3572e15f0fb8f058ae019352b13849c Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 9 Jun 2025 16:17:34 +0700
Subject: [PATCH 01/29] init generate-llms-txt

---
 .../scripts/generate-llms-txt/src/index.ts    |  95 +++++++++++
 .../generate-llms-txt/test/index.test.ts      | 156 ++++++++++++++++++
 .../scripts/generate-llms-txt/tsconfig.json   |  12 ++
 .../generate-llms-txt/tsconfig.test.json      |  12 ++
 packages-internal/scripts/package.json        |   6 +-
 packages-internal/scripts/tsconfig.json       |   2 +-
 tsconfig.json                                 |   3 +
 7 files changed, 284 insertions(+), 2 deletions(-)
 create mode 100755 packages-internal/scripts/generate-llms-txt/src/index.ts
 create mode 100644 packages-internal/scripts/generate-llms-txt/test/index.test.ts
 create mode 100644 packages-internal/scripts/generate-llms-txt/tsconfig.json
 create mode 100644 packages-internal/scripts/generate-llms-txt/tsconfig.test.json

diff --git a/packages-internal/scripts/generate-llms-txt/src/index.ts b/packages-internal/scripts/generate-llms-txt/src/index.ts
new file mode 100755
index 00000000000000..c4ab2ec042f715
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/src/index.ts
@@ -0,0 +1,95 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface DemoReplaceOptions {
+  basePath?: string;
+  includeTypeScript?: boolean;
+}
+
+/**
+ * Parses markdown content and replaces demo syntax with code snippets
+ * @param markdownContent - The markdown content to parse
+ * @param markdownPath - The path to the markdown file (used to resolve relative demo paths)
+ * @param options - Options for parsing
+ * @returns The processed markdown with demo code snippets
+ */
+export function replaceDemoWithSnippet(
+  markdownContent: string,
+  markdownPath: string,
+  options: DemoReplaceOptions = {}
+): string {
+  const { basePath = '', includeTypeScript = true } = options;
+  
+  // Regular expression to match {{"demo": "filename.js"}} pattern
+  const demoRegex = /\{\{"demo":\s*"([^"]+)"(?:,\s*[^}]+)?\}\}/g;
+  
+  return markdownContent.replace(demoRegex, (match, filename) => {
+    try {
+      // Extract the base filename without extension
+      const baseFilename = filename.replace(/\.(js|tsx?)$/, '');
+      
+      // Get the directory of the markdown file
+      const markdownDir = path.dirname(markdownPath);
+      
+      let codeSnippet = '';
+      
+      // Try to read JavaScript file
+      const jsPath = basePath ? 
+        path.join(basePath, `${baseFilename}.js`) : 
+        path.join(markdownDir, `${baseFilename}.js`);
+        
+      if (fs.existsSync(jsPath)) {
+        const jsContent = fs.readFileSync(jsPath, 'utf-8');
+        codeSnippet += `\`\`\`jsx\n${jsContent}\n\`\`\``;
+      }
+      
+      // Try to read TypeScript file if includeTypeScript is true
+      if (includeTypeScript) {
+        const tsPath = basePath ? 
+          path.join(basePath, `${baseFilename}.tsx`) : 
+          path.join(markdownDir, `${baseFilename}.tsx`);
+          
+        if (fs.existsSync(tsPath)) {
+          const tsContent = fs.readFileSync(tsPath, 'utf-8');
+          if (codeSnippet) {
+            codeSnippet += '\n\n';
+          }
+          codeSnippet += `\`\`\`tsx\n${tsContent}\n\`\`\``;
+        }
+      }
+      
+      // If no files found, return original match
+      if (!codeSnippet) {
+        console.warn(`Demo file not found: ${filename}`);
+        return match;
+      }
+      
+      return codeSnippet;
+    } catch (error) {
+      console.error(`Error processing demo ${filename}:`, error);
+      return match;
+    }
+  });
+}
+
+/**
+ * Processes a markdown file and replaces demo syntax with code snippets
+ * @param filePath - Path to the markdown file
+ * @param options - Options for parsing
+ * @returns The processed markdown content
+ */
+export function processMarkdownFile(
+  filePath: string,
+  options: DemoReplaceOptions = {}
+): string {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const dir = path.dirname(filePath);
+  
+  // Set basePath relative to markdown file location if not provided
+  const processOptions = {
+    ...options,
+    basePath: options.basePath || dir,
+  };
+  
+  return replaceDemoWithSnippet(content, filePath, processOptions);
+}
\ No newline at end of file
diff --git a/packages-internal/scripts/generate-llms-txt/test/index.test.ts b/packages-internal/scripts/generate-llms-txt/test/index.test.ts
new file mode 100644
index 00000000000000..062068c86b8462
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/test/index.test.ts
@@ -0,0 +1,156 @@
+import { expect } from 'chai';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { replaceDemoWithSnippet, processMarkdownFile } from '../src/index';
+
+describe('generate-llms-txt', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    // Create a temporary directory for test files
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'llms-txt-test-'));
+  });
+
+  afterEach(() => {
+    // Clean up temporary directory
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('replaceDemoWithSnippet', () => {
+    it('should replace demo syntax with code snippet', () => {
+      const markdown = `# Test Component
+
+Here is a demo:
+
+{{"demo": "BasicButton.js"}}
+
+More content here.`;
+
+      const jsContent = `import React from 'react';
+
+export default function BasicButton() {
+  return <button>Click me</button>;
+}`;
+
+      // Create test files
+      fs.writeFileSync(path.join(tempDir, 'BasicButton.js'), jsContent);
+
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+
+      expect(result).to.include('```jsx');
+      expect(result).to.include(jsContent);
+      expect(result).to.not.include('{{"demo": "BasicButton.js"}}');
+    });
+
+    it('should include both JS and TS files when includeTypeScript is true', () => {
+      const markdown = `{{"demo": "Component.js"}}`;
+
+      const jsContent = `// JavaScript version`;
+      const tsContent = `// TypeScript version`;
+
+      fs.writeFileSync(path.join(tempDir, 'Component.js'), jsContent);
+      fs.writeFileSync(path.join(tempDir, 'Component.tsx'), tsContent);
+
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { 
+        basePath: tempDir,
+        includeTypeScript: true 
+      });
+
+      expect(result).to.include('```jsx');
+      expect(result).to.include(jsContent);
+      expect(result).to.include('```tsx');
+      expect(result).to.include(tsContent);
+    });
+
+    it('should only include JS file when includeTypeScript is false', () => {
+      const markdown = `{{"demo": "Component.js"}}`;
+
+      const jsContent = `// JavaScript version`;
+      const tsContent = `// TypeScript version`;
+
+      fs.writeFileSync(path.join(tempDir, 'Component.js'), jsContent);
+      fs.writeFileSync(path.join(tempDir, 'Component.tsx'), tsContent);
+
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { 
+        basePath: tempDir,
+        includeTypeScript: false 
+      });
+
+      expect(result).to.include('```jsx');
+      expect(result).to.include(jsContent);
+      expect(result).to.not.include('```tsx');
+      expect(result).to.not.include(tsContent);
+    });
+
+    it('should handle multiple demos in the same markdown', () => {
+      const markdown = `# Multiple Demos
+
+{{"demo": "First.js"}}
+
+Some text in between.
+
+{{"demo": "Second.js"}}`;
+
+      fs.writeFileSync(path.join(tempDir, 'First.js'), 'First component');
+      fs.writeFileSync(path.join(tempDir, 'Second.js'), 'Second component');
+
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+
+      expect(result).to.include('First component');
+      expect(result).to.include('Second component');
+      expect(result.match(/```jsx/g)).to.have.lengthOf(2);
+    });
+
+    it('should return original match when demo file is not found', () => {
+      const markdown = `{{"demo": "NonExistent.js"}}`;
+
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+
+      expect(result).to.equal(markdown);
+    });
+
+    it('should handle demos with additional properties', () => {
+      const markdown = `{{"demo": "Button.js", "defaultCodeOpen": false}}`;
+
+      fs.writeFileSync(path.join(tempDir, 'Button.js'), 'Button code');
+
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+
+      expect(result).to.include('```jsx');
+      expect(result).to.include('Button code');
+    });
+  });
+
+  describe('processMarkdownFile', () => {
+    it('should process a markdown file correctly', () => {
+      const markdownPath = path.join(tempDir, 'test.md');
+      const markdown = `# Test
+
+{{"demo": "Demo.js"}}`;
+
+      fs.writeFileSync(markdownPath, markdown);
+      fs.writeFileSync(path.join(tempDir, 'Demo.js'), 'Demo content');
+
+      const result = processMarkdownFile(markdownPath);
+
+      expect(result).to.include('```jsx');
+      expect(result).to.include('Demo content');
+    });
+
+    it('should handle nested directory structures', () => {
+      const subDir = path.join(tempDir, 'components', 'buttons');
+      fs.mkdirSync(subDir, { recursive: true });
+
+      const markdownPath = path.join(subDir, 'buttons.md');
+      const markdown = `{{"demo": "BasicButton.js"}}`;
+
+      fs.writeFileSync(markdownPath, markdown);
+      fs.writeFileSync(path.join(subDir, 'BasicButton.js'), 'Button component');
+
+      const result = processMarkdownFile(markdownPath);
+
+      expect(result).to.include('Button component');
+    });
+  });
+});
\ No newline at end of file
diff --git a/packages-internal/scripts/generate-llms-txt/tsconfig.json b/packages-internal/scripts/generate-llms-txt/tsconfig.json
new file mode 100644
index 00000000000000..38c3e68e347578
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "../build/generate-llms-txt",
+    "tsBuildInfoFile": "../build/generate-llms-txt/.tsbuildinfo",
+    "noImplicitAny": false,
+    "strict": false,
+    "skipLibCheck": true
+  },
+  "include": ["./src/*"]
+}
diff --git a/packages-internal/scripts/generate-llms-txt/tsconfig.test.json b/packages-internal/scripts/generate-llms-txt/tsconfig.test.json
new file mode 100644
index 00000000000000..a42c4b79a01b78
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/tsconfig.test.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "moduleResolution": "",
+    "types": ["node", "mocha"],
+    "strict": true,
+    "esModuleInterop": true,
+    "isolatedModules": true
+  },
+  "include": ["./src/*.ts", "./test/*.ts"],
+  "references": [{ "path": "../../docs-utils/tsconfig.build.json" }]
+}
diff --git a/packages-internal/scripts/package.json b/packages-internal/scripts/package.json
index fef8cc072a2092..8e66bb3c7314f1 100644
--- a/packages-internal/scripts/package.json
+++ b/packages-internal/scripts/package.json
@@ -8,6 +8,10 @@
     "./typescript-to-proptypes": {
       "types": "./build/typescript-to-proptypes/index.d.ts",
       "default": "./build/typescript-to-proptypes/index.js"
+    },
+    "./generate-llms-txt": {
+      "types": "./build/generate-llms-txt/index.d.ts",
+      "default": "./build/generate-llms-txt/index.js"
     }
   },
   "repository": {
@@ -21,7 +25,7 @@
     "build": "tsc --build tsconfig.json",
     "release:publish": "pnpm build && pnpm publish --tag latest",
     "release:publish:dry-run": "pnpm build && pnpm publish --tag latest --registry=\"http://localhost:4873/\"",
-    "test": "cd ../../ && cross-env NODE_ENV=test mocha --config packages-internal/scripts/typescript-to-proptypes/test/.mocharc.js 'packages-internal/scripts/typescript-to-proptypes/**/*.test.?(c|m)[jt]s?(x)'",
+    "test": "cd ../../ && cross-env NODE_ENV=test mocha --config packages-internal/scripts/typescript-to-proptypes/test/.mocharc.js 'packages-internal/scripts/typescript-to-proptypes/**/*.test.?(c|m)[jt]s?(x)' 'packages-internal/scripts/generate-llms-txt/**/*.test.?(c|m)[jt]s?(x)'",
     "typescript": "tsc --build tsconfig.typecheck.json"
   },
   "dependencies": {
diff --git a/packages-internal/scripts/tsconfig.json b/packages-internal/scripts/tsconfig.json
index beb8da4f93e065..777e079ed618c2 100644
--- a/packages-internal/scripts/tsconfig.json
+++ b/packages-internal/scripts/tsconfig.json
@@ -1,5 +1,5 @@
 {
   "files": [],
   "include": [],
-  "references": [{ "path": "./typescript-to-proptypes" }]
+  "references": [{ "path": "./typescript-to-proptypes" }, { "path": "./generate-llms-txt" }]
 }
diff --git a/tsconfig.json b/tsconfig.json
index 676b002f9dbf7b..7552e3d446288f 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -46,6 +46,9 @@
       "@mui/internal-scripts/typescript-to-proptypes": [
         "./packages-internal/scripts/typescript-to-proptypes/src"
       ],
+      "@mui/internal-scripts/generate-llms-txt": [
+        "./packages-internal/scripts/generate-llms-txt/src"
+      ],
       "@mui/internal-test-utils": ["./packages-internal/test-utils/src"],
       "@mui/internal-test-utils/*": ["./packages-internal/test-utils/src/*"],
       "@mui/stylis-plugin-rtl": ["./packages/mui-stylis-plugin-rtl/src"],

From 1b98e4a1422e467a8c2ee82c3b97c8701b9591a2 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 9 Jun 2025 18:21:14 +0700
Subject: [PATCH 02/29] able to generate components and api

---
 .../scripts/generate-llms-txt/src/index.ts    |  98 +----
 .../generate-llms-txt/src/processApi.ts       | 288 ++++++++++++++
 .../generate-llms-txt/src/processComponent.ts |  95 +++++
 .../generate-llms-txt/test/processApi.test.ts | 363 ++++++++++++++++++
 ...index.test.ts => processComponent.test.ts} |   0
 scripts/buildLlmsDocs/index.ts                | 205 ++++++++++
 scripts/buildLlmsDocs/tsconfig.json           |  10 +
 7 files changed, 964 insertions(+), 95 deletions(-)
 mode change 100755 => 100644 packages-internal/scripts/generate-llms-txt/src/index.ts
 create mode 100644 packages-internal/scripts/generate-llms-txt/src/processApi.ts
 create mode 100755 packages-internal/scripts/generate-llms-txt/src/processComponent.ts
 create mode 100644 packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
 rename packages-internal/scripts/generate-llms-txt/test/{index.test.ts => processComponent.test.ts} (100%)
 create mode 100644 scripts/buildLlmsDocs/index.ts
 create mode 100644 scripts/buildLlmsDocs/tsconfig.json

diff --git a/packages-internal/scripts/generate-llms-txt/src/index.ts b/packages-internal/scripts/generate-llms-txt/src/index.ts
old mode 100755
new mode 100644
index c4ab2ec042f715..85d2b6af02fe09
--- a/packages-internal/scripts/generate-llms-txt/src/index.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/index.ts
@@ -1,95 +1,3 @@
-import * as fs from 'fs';
-import * as path from 'path';
-
-interface DemoReplaceOptions {
-  basePath?: string;
-  includeTypeScript?: boolean;
-}
-
-/**
- * Parses markdown content and replaces demo syntax with code snippets
- * @param markdownContent - The markdown content to parse
- * @param markdownPath - The path to the markdown file (used to resolve relative demo paths)
- * @param options - Options for parsing
- * @returns The processed markdown with demo code snippets
- */
-export function replaceDemoWithSnippet(
-  markdownContent: string,
-  markdownPath: string,
-  options: DemoReplaceOptions = {}
-): string {
-  const { basePath = '', includeTypeScript = true } = options;
-  
-  // Regular expression to match {{"demo": "filename.js"}} pattern
-  const demoRegex = /\{\{"demo":\s*"([^"]+)"(?:,\s*[^}]+)?\}\}/g;
-  
-  return markdownContent.replace(demoRegex, (match, filename) => {
-    try {
-      // Extract the base filename without extension
-      const baseFilename = filename.replace(/\.(js|tsx?)$/, '');
-      
-      // Get the directory of the markdown file
-      const markdownDir = path.dirname(markdownPath);
-      
-      let codeSnippet = '';
-      
-      // Try to read JavaScript file
-      const jsPath = basePath ? 
-        path.join(basePath, `${baseFilename}.js`) : 
-        path.join(markdownDir, `${baseFilename}.js`);
-        
-      if (fs.existsSync(jsPath)) {
-        const jsContent = fs.readFileSync(jsPath, 'utf-8');
-        codeSnippet += `\`\`\`jsx\n${jsContent}\n\`\`\``;
-      }
-      
-      // Try to read TypeScript file if includeTypeScript is true
-      if (includeTypeScript) {
-        const tsPath = basePath ? 
-          path.join(basePath, `${baseFilename}.tsx`) : 
-          path.join(markdownDir, `${baseFilename}.tsx`);
-          
-        if (fs.existsSync(tsPath)) {
-          const tsContent = fs.readFileSync(tsPath, 'utf-8');
-          if (codeSnippet) {
-            codeSnippet += '\n\n';
-          }
-          codeSnippet += `\`\`\`tsx\n${tsContent}\n\`\`\``;
-        }
-      }
-      
-      // If no files found, return original match
-      if (!codeSnippet) {
-        console.warn(`Demo file not found: ${filename}`);
-        return match;
-      }
-      
-      return codeSnippet;
-    } catch (error) {
-      console.error(`Error processing demo ${filename}:`, error);
-      return match;
-    }
-  });
-}
-
-/**
- * Processes a markdown file and replaces demo syntax with code snippets
- * @param filePath - Path to the markdown file
- * @param options - Options for parsing
- * @returns The processed markdown content
- */
-export function processMarkdownFile(
-  filePath: string,
-  options: DemoReplaceOptions = {}
-): string {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const dir = path.dirname(filePath);
-  
-  // Set basePath relative to markdown file location if not provided
-  const processOptions = {
-    ...options,
-    basePath: options.basePath || dir,
-  };
-  
-  return replaceDemoWithSnippet(content, filePath, processOptions);
-}
\ No newline at end of file
+// Export all functions from both modules
+export * from './processComponent';
+export * from './processApi';
\ No newline at end of file
diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
new file mode 100644
index 00000000000000..e3f608e0dbb738
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -0,0 +1,288 @@
+import * as fs from 'fs';
+
+interface ApiProp {
+  type: {
+    name: string;
+    description?: string;
+  };
+  required?: boolean;
+  default?: string;
+  deprecated?: boolean;
+  deprecationInfo?: string;
+  signature?: {
+    type: string;
+    describedArgs?: string[];
+  };
+  additionalInfo?: {
+    cssApi?: boolean;
+    sx?: boolean;
+  };
+}
+
+interface ApiSlot {
+  name: string;
+  description: string;
+  default: string;
+  class: string | null;
+}
+
+interface ApiClass {
+  key: string;
+  className: string;
+  description: string;
+  isGlobal: boolean;
+}
+
+interface ApiInheritance {
+  component: string;
+  pathname: string;
+}
+
+interface ApiJson {
+  props: Record<string, ApiProp>;
+  name: string;
+  imports: string[];
+  slots?: ApiSlot[];
+  classes?: ApiClass[];
+  spread?: boolean;
+  themeDefaultProps?: boolean;
+  muiName?: string;
+  forwardsRefTo?: string | null;
+  filename?: string;
+  inheritance?: ApiInheritance;
+  demos?: string;
+  cssComponent?: boolean;
+  deprecated?: boolean;
+  deprecationInfo?: string;
+}
+
+/**
+ * Convert HTML to markdown
+ */
+function htmlToMarkdown(html: string): string {
+  return html
+    // Decode HTML entities first
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#124;/g, '|')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    // Convert <br> to space for inline content (not newline for table cells)
+    .replace(/<br\s*\/?>/gi, ' ')
+    // Convert <code> to backticks
+    .replace(/<code>([^<]+)<\/code>/gi, '`$1`')
+    // Convert <a> to markdown links
+    .replace(/<a\s+href="([^"]+)">([^<]+)<\/a>/gi, '[$2]($1)')
+    // Convert <ul> and <li> to markdown lists (only for block content)
+    .replace(/<ul>/gi, '')
+    .replace(/<\/ul>/gi, '')
+    .replace(/<li>/gi, '- ')
+    .replace(/<\/li>/gi, '')
+    // Convert <p> to double newline (only for block content)
+    .replace(/<p>/gi, '\n\n')
+    .replace(/<\/p>/gi, '')
+    // Remove any remaining HTML tags
+    .replace(/<[^>]+>/g, '')
+    // Clean up excessive whitespace and newlines
+    .replace(/\s+/g, ' ')
+    .replace(/\n\s+/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * Format prop type for markdown
+ */
+function formatPropType(prop: ApiProp): string {
+  let type = prop.type.name;
+  
+  if (prop.type.description) {
+    // Clean up the description
+    type = htmlToMarkdown(prop.type.description);
+  }
+  
+  if (prop.signature) {
+    type = `\`${prop.signature.type}\``;
+  }
+  
+  return type;
+}
+
+/**
+ * Generate props table
+ */
+function generatePropsTable(props: Record<string, ApiProp>): string {
+  const propEntries = Object.entries(props);
+  if (propEntries.length === 0) {
+    return '';
+  }
+
+  let table = '## Props\n\n';
+  table += '| Name | Type | Default | Required | Description |\n';
+  table += '|------|------|---------|----------|-------------|\n';
+
+  for (const [propName, prop] of propEntries) {
+    const name = prop.deprecated ? `${propName} (deprecated)` : propName;
+    const type = formatPropType(prop);
+    const defaultValue = prop.default ? `\`${prop.default}\`` : '-';
+    const required = prop.required ? 'Yes' : 'No';
+    
+    let description = '';
+    if (prop.deprecated && prop.deprecationInfo) {
+      description = `⚠️ ${htmlToMarkdown(prop.deprecationInfo)}`;
+    } else if (prop.additionalInfo?.cssApi) {
+      description = 'Override or extend the styles applied to the component.';
+    } else if (prop.additionalInfo?.sx) {
+      description = 'The system prop that allows defining system overrides as well as additional CSS styles.';
+    }
+
+    table += `| ${name} | ${type} | ${defaultValue} | ${required} | ${description} |\n`;
+  }
+
+  return table;
+}
+
+/**
+ * Generate slots table
+ */
+function generateSlotsTable(slots: ApiSlot[]): string {
+  if (!slots || slots.length === 0) {
+    return '';
+  }
+
+  let table = '## Slots\n\n';
+  table += '| Name | Default | Class | Description |\n';
+  table += '|------|---------|-------|-------------|\n';
+
+  for (const slot of slots) {
+    const className = slot.class ? `\`.${slot.class}\`` : '-';
+    const description = htmlToMarkdown(slot.description);
+    table += `| ${slot.name} | \`${slot.default}\` | ${className} | ${description} |\n`;
+  }
+
+  return table;
+}
+
+/**
+ * Generate classes table
+ */
+function generateClassesTable(classes: ApiClass[]): string {
+  if (!classes || classes.length === 0) {
+    return '';
+  }
+
+  let table = '## CSS\n\n';
+  table += '### Rule name\n\n';
+  table += '| Global class | Rule name | Description |\n';
+  table += '|--------------|-----------|-------------|\n';
+
+  for (const cls of classes) {
+    const globalClass = cls.isGlobal ? `\`.${cls.className}\`` : '-';
+    const ruleName = cls.isGlobal ? '-' : cls.key;
+    const description = htmlToMarkdown(cls.description);
+    table += `| ${globalClass} | ${ruleName} | ${description} |\n`;
+  }
+
+  return table;
+}
+
+/**
+ * Process API JSON and convert to markdown
+ */
+export function processApiJson(apiJson: ApiJson | string): string {
+  const api: ApiJson = typeof apiJson === 'string' ? JSON.parse(apiJson) : apiJson;
+  
+  let markdown = `# ${api.name} API\n\n`;
+
+  // Add deprecation warning if applicable
+  if (api.deprecated) {
+    const warningText = api.deprecationInfo ? htmlToMarkdown(api.deprecationInfo) : 
+      'This component is deprecated. Consider using an alternative component.';
+    markdown += `> ⚠️ **Warning**: ${warningText}\n\n`;
+  }
+
+  // Add demos section
+  if (api.demos) {
+    markdown += '## Demos\n\n';
+    markdown += 'For examples and details on the usage of this React component, visit the component demo pages:\n\n';
+    markdown += htmlToMarkdown(api.demos) + '\n\n';
+  }
+
+  // Add import section
+  markdown += '## Import\n\n';
+  markdown += '```jsx\n';
+  markdown += api.imports.join('\n// or\n');
+  markdown += '\n```\n\n';
+
+  // Add props section
+  const propsTable = generatePropsTable(api.props);
+  if (propsTable) {
+    markdown += propsTable + '\n';
+  }
+
+  // Add ref information
+  if (api.forwardsRefTo === null) {
+    markdown += '> **Note**: This component cannot hold a ref.\n\n';
+  } else {
+    markdown += `> **Note**: The \`ref\` is forwarded to the root element${api.forwardsRefTo ? ` (${api.forwardsRefTo})` : ''}.\n\n`;
+  }
+
+  // Add spread information
+  if (api.spread) {
+    const spreadElement = api.inheritance ? 
+      `[${api.inheritance.component}](${api.inheritance.pathname})` : 
+      'native element';
+    markdown += `> Any other props supplied will be provided to the root element (${spreadElement}).\n\n`;
+  }
+
+  // Add inheritance section
+  if (api.inheritance) {
+    markdown += '## Inheritance\n\n';
+    markdown += `While not explicitly documented above, the props of the [${api.inheritance.component}](${api.inheritance.pathname}) component are also available on ${api.name}.`;
+    if (api.inheritance.component === 'Transition') {
+      markdown += ' A subset of components support [react-transition-group](https://reactcommunity.org/react-transition-group/transition/) out of the box.';
+    }
+    markdown += '\n\n';
+  }
+
+  // Add theme default props section
+  if (api.themeDefaultProps && api.muiName) {
+    markdown += '## Theme default props\n\n';
+    markdown += `You can use \`${api.muiName}\` to change the default props of this component with the theme.\n\n`;
+  }
+
+  // Add slots section
+  const slotsTable = generateSlotsTable(api.slots || []);
+  if (slotsTable) {
+    markdown += slotsTable + '\n';
+  }
+
+  // Add classes section
+  const classesTable = generateClassesTable(api.classes || []);
+  if (classesTable) {
+    markdown += classesTable + '\n';
+  }
+
+  // Add CSS component note
+  if (api.cssComponent) {
+    markdown += `> **Note**: As a CSS utility, the \`${api.name}\` component also supports all system properties. You can use them as props directly on the component.\n\n`;
+  }
+
+  // Add source code section
+  if (api.filename) {
+    markdown += '## Source code\n\n';
+    markdown += `If you did not find the information on this page, consider having a look at the implementation of the component for more detail.\n\n`;
+    markdown += `- [${api.filename}](https://github.com/mui/material-ui/tree/HEAD${api.filename})\n\n`;
+  }
+
+  return markdown.trim();
+}
+
+/**
+ * Process API JSON file and return markdown
+ */
+export function processApiFile(filePath: string): string {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return processApiJson(content);
+}
\ No newline at end of file
diff --git a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
new file mode 100755
index 00000000000000..c4ab2ec042f715
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
@@ -0,0 +1,95 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface DemoReplaceOptions {
+  basePath?: string;
+  includeTypeScript?: boolean;
+}
+
+/**
+ * Parses markdown content and replaces demo syntax with code snippets
+ * @param markdownContent - The markdown content to parse
+ * @param markdownPath - The path to the markdown file (used to resolve relative demo paths)
+ * @param options - Options for parsing
+ * @returns The processed markdown with demo code snippets
+ */
+export function replaceDemoWithSnippet(
+  markdownContent: string,
+  markdownPath: string,
+  options: DemoReplaceOptions = {}
+): string {
+  const { basePath = '', includeTypeScript = true } = options;
+  
+  // Regular expression to match {{"demo": "filename.js"}} pattern
+  const demoRegex = /\{\{"demo":\s*"([^"]+)"(?:,\s*[^}]+)?\}\}/g;
+  
+  return markdownContent.replace(demoRegex, (match, filename) => {
+    try {
+      // Extract the base filename without extension
+      const baseFilename = filename.replace(/\.(js|tsx?)$/, '');
+      
+      // Get the directory of the markdown file
+      const markdownDir = path.dirname(markdownPath);
+      
+      let codeSnippet = '';
+      
+      // Try to read JavaScript file
+      const jsPath = basePath ? 
+        path.join(basePath, `${baseFilename}.js`) : 
+        path.join(markdownDir, `${baseFilename}.js`);
+        
+      if (fs.existsSync(jsPath)) {
+        const jsContent = fs.readFileSync(jsPath, 'utf-8');
+        codeSnippet += `\`\`\`jsx\n${jsContent}\n\`\`\``;
+      }
+      
+      // Try to read TypeScript file if includeTypeScript is true
+      if (includeTypeScript) {
+        const tsPath = basePath ? 
+          path.join(basePath, `${baseFilename}.tsx`) : 
+          path.join(markdownDir, `${baseFilename}.tsx`);
+          
+        if (fs.existsSync(tsPath)) {
+          const tsContent = fs.readFileSync(tsPath, 'utf-8');
+          if (codeSnippet) {
+            codeSnippet += '\n\n';
+          }
+          codeSnippet += `\`\`\`tsx\n${tsContent}\n\`\`\``;
+        }
+      }
+      
+      // If no files found, return original match
+      if (!codeSnippet) {
+        console.warn(`Demo file not found: ${filename}`);
+        return match;
+      }
+      
+      return codeSnippet;
+    } catch (error) {
+      console.error(`Error processing demo ${filename}:`, error);
+      return match;
+    }
+  });
+}
+
+/**
+ * Processes a markdown file and replaces demo syntax with code snippets
+ * @param filePath - Path to the markdown file
+ * @param options - Options for parsing
+ * @returns The processed markdown content
+ */
+export function processMarkdownFile(
+  filePath: string,
+  options: DemoReplaceOptions = {}
+): string {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const dir = path.dirname(filePath);
+  
+  // Set basePath relative to markdown file location if not provided
+  const processOptions = {
+    ...options,
+    basePath: options.basePath || dir,
+  };
+  
+  return replaceDemoWithSnippet(content, filePath, processOptions);
+}
\ No newline at end of file
diff --git a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
new file mode 100644
index 00000000000000..8ca4754f76d56f
--- /dev/null
+++ b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
@@ -0,0 +1,363 @@
+import { expect } from 'chai';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { processApiJson, processApiFile } from '../src/processApi';
+
+describe('processApi', () => {
+  describe('processApiJson', () => {
+    it('should generate basic component API markdown', () => {
+      const apiJson = {
+        name: 'Button',
+        imports: [
+          "import Button from '@mui/material/Button';",
+          "import { Button } from '@mui/material';"
+        ],
+        props: {
+          color: {
+            type: { name: 'string' },
+            default: "'primary'",
+            required: false
+          },
+          disabled: {
+            type: { name: 'bool' },
+            default: 'false',
+            required: false
+          }
+        }
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('# Button API');
+      expect(result).to.include('## Import');
+      expect(result).to.include("import Button from '@mui/material/Button';");
+      expect(result).to.include('## Props');
+      expect(result).to.include('| color | string | `\'primary\'` | No |');
+      expect(result).to.include('| disabled | bool | `false` | No |');
+    });
+
+    it('should handle deprecated component', () => {
+      const apiJson = {
+        name: 'DeprecatedComponent',
+        imports: ["import DeprecatedComponent from '@mui/material/DeprecatedComponent';"],
+        props: {},
+        deprecated: true,
+        deprecationInfo: 'Use <code>NewComponent</code> instead.'
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('> ⚠️ **Warning**: Use `NewComponent` instead.');
+    });
+
+    it('should handle deprecated props', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {
+          oldProp: {
+            type: { name: 'string' },
+            deprecated: true,
+            deprecationInfo: 'Use <code>newProp</code> instead.'
+          }
+        }
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('| oldProp (deprecated) |');
+      expect(result).to.include('⚠️ Use `newProp` instead.');
+    });
+
+    it('should handle complex prop types', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {
+          onChange: {
+            type: { name: 'func' },
+            signature: {
+              type: 'function(event: React.SyntheticEvent, value: number) => void',
+              describedArgs: ['event', 'value']
+            }
+          },
+          slots: {
+            type: {
+              name: 'shape',
+              description: '{ root?: elementType, icon?: elementType }'
+            }
+          },
+          sx: {
+            type: {
+              name: 'union',
+              description: 'Array&lt;func<br>&#124;&nbsp;object&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object'
+            },
+            additionalInfo: { sx: true }
+          }
+        }
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('`function(event: React.SyntheticEvent, value: number) => void`');
+      expect(result).to.include('{ root?: elementType, icon?: elementType }');
+      expect(result).to.include('Array<func | object> | func | object');
+      expect(result).to.include('The system prop that allows defining system overrides');
+    });
+
+    it('should handle demos section', () => {
+      const apiJson = {
+        name: 'Accordion',
+        imports: ["import Accordion from '@mui/material/Accordion';"],
+        props: {},
+        demos: '<ul><li><a href="/material-ui/react-accordion/">Accordion</a></li></ul>'
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('## Demos');
+      expect(result).to.include('- [Accordion](/material-ui/react-accordion/)');
+    });
+
+    it('should handle slots section', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {},
+        slots: [
+          {
+            name: 'root',
+            description: 'The component that renders the root.',
+            default: 'Paper',
+            class: 'MuiComponent-root'
+          },
+          {
+            name: 'icon',
+            description: 'The icon element.',
+            default: 'svg',
+            class: null
+          }
+        ]
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('## Slots');
+      expect(result).to.include('| root | `Paper` | `.MuiComponent-root` | The component that renders the root. |');
+      expect(result).to.include('| icon | `svg` | - | The icon element. |');
+    });
+
+    it('should handle classes section', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {},
+        classes: [
+          {
+            key: 'disabled',
+            className: 'Mui-disabled',
+            description: 'State class applied to the root element if `disabled={true}`.',
+            isGlobal: true
+          },
+          {
+            key: 'root',
+            className: 'MuiComponent-root',
+            description: 'Styles applied to the root element.',
+            isGlobal: false
+          }
+        ]
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('## CSS');
+      expect(result).to.include('### Rule name');
+      expect(result).to.include('| `.Mui-disabled` | - | State class applied to the root element if `disabled={true}`. |');
+      expect(result).to.include('| - | root | Styles applied to the root element. |');
+    });
+
+    it('should handle inheritance', () => {
+      const apiJson = {
+        name: 'Accordion',
+        imports: ["import Accordion from '@mui/material/Accordion';"],
+        props: {},
+        inheritance: {
+          component: 'Paper',
+          pathname: '/material-ui/api/paper/'
+        }
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('## Inheritance');
+      expect(result).to.include('[Paper](/material-ui/api/paper/)');
+      expect(result).to.include('the props of the [Paper](/material-ui/api/paper/) component are also available on Accordion');
+    });
+
+    it('should handle spread props', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {},
+        spread: true,
+        inheritance: {
+          component: 'Paper',
+          pathname: '/material-ui/api/paper/'
+        }
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('Any other props supplied will be provided to the root element ([Paper](/material-ui/api/paper/))');
+    });
+
+    it('should handle ref forwarding', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {},
+        forwardsRefTo: 'HTMLDivElement'
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('The `ref` is forwarded to the root element (HTMLDivElement)');
+    });
+
+    it('should handle components that cannot hold refs', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {},
+        forwardsRefTo: null
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('This component cannot hold a ref');
+    });
+
+    it('should handle theme default props', () => {
+      const apiJson = {
+        name: 'Button',
+        imports: ["import Button from '@mui/material/Button';"],
+        props: {},
+        themeDefaultProps: true,
+        muiName: 'MuiButton'
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('## Theme default props');
+      expect(result).to.include('You can use `MuiButton` to change the default props');
+    });
+
+    it('should handle CSS component', () => {
+      const apiJson = {
+        name: 'Box',
+        imports: ["import Box from '@mui/material/Box';"],
+        props: {},
+        cssComponent: true
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('As a CSS utility, the `Box` component also supports all system properties');
+    });
+
+    it('should handle source code section', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {},
+        filename: '/packages/mui-material/src/Component/Component.js'
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('## Source code');
+      expect(result).to.include('https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/Component/Component.js');
+    });
+
+    it('should handle required props', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {
+          children: {
+            type: { name: 'node' },
+            required: true
+          },
+          optional: {
+            type: { name: 'string' },
+            required: false
+          }
+        }
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('| children | node | - | Yes |');
+      expect(result).to.include('| optional | string | - | No |');
+    });
+  });
+
+  describe('processApiFile', () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'api-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it('should process API JSON file', () => {
+      const apiJson = {
+        name: 'TestComponent',
+        imports: ["import TestComponent from '@mui/material/TestComponent';"],
+        props: {
+          test: {
+            type: { name: 'bool' },
+            default: 'true'
+          }
+        }
+      };
+
+      const filePath = path.join(tempDir, 'test-component.json');
+      fs.writeFileSync(filePath, JSON.stringify(apiJson, null, 2));
+
+      const result = processApiFile(filePath);
+
+      expect(result).to.include('# TestComponent API');
+      expect(result).to.include('| test | bool | `true` | No |');
+    });
+  });
+
+  describe('HTML to Markdown conversion', () => {
+    it('should convert HTML entities and tags correctly', () => {
+      const apiJson = {
+        name: 'Component',
+        imports: ["import Component from '@mui/material/Component';"],
+        props: {
+          complexProp: {
+            type: {
+              name: 'union',
+              description: 'Array&lt;func<br>&#124;&nbsp;object&gt;<br>&#124;&nbsp;func'
+            }
+          }
+        },
+        demos: '<p>Test paragraph</p><ul><li>Item 1</li><li>Item 2</li></ul>'
+      };
+
+      const result = processApiJson(apiJson);
+
+      expect(result).to.include('Array<func | object> | func');
+      expect(result).to.include('Test paragraph');
+      expect(result).to.include('- Item 1');
+      expect(result).to.include('- Item 2');
+    });
+  });
+});
\ No newline at end of file
diff --git a/packages-internal/scripts/generate-llms-txt/test/index.test.ts b/packages-internal/scripts/generate-llms-txt/test/processComponent.test.ts
similarity index 100%
rename from packages-internal/scripts/generate-llms-txt/test/index.test.ts
rename to packages-internal/scripts/generate-llms-txt/test/processComponent.test.ts
diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
new file mode 100644
index 00000000000000..e40fd62776fb53
--- /dev/null
+++ b/scripts/buildLlmsDocs/index.ts
@@ -0,0 +1,205 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import yargs, { ArgumentsCamelCase } from 'yargs';
+import { processMarkdownFile, processApiFile } from '@mui/internal-scripts/generate-llms-txt';
+import { getMaterialUiComponentInfo } from '../../packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo';
+import { projectSettings } from '../../packages/api-docs-builder-core/materialUi/projectSettings';
+
+interface ComponentDocInfo {
+  name: string;
+  markdownPath: string;
+  apiJsonPath?: string;
+}
+
+type CommandOptions = { 
+  grep?: string; 
+  outputDir?: string;
+  includeApi?: boolean;
+};
+
+/**
+ * Find all component markdown files and map them to API files using the API docs builder
+ */
+function findComponentMarkdownFiles(baseDir: string, grep?: RegExp): ComponentDocInfo[] {
+  const componentsDir = path.join(baseDir, 'docs/data/material/components');
+  const components: ComponentDocInfo[] = [];
+  
+  if (!fs.existsSync(componentsDir)) {
+    throw new Error(`Components directory not found: ${componentsDir}`);
+  }
+  
+  const componentDirs = fs.readdirSync(componentsDir, { withFileTypes: true })
+    .filter(dirent => dirent.isDirectory())
+    .map(dirent => dirent.name);
+  
+  // Get all API pages to create a reverse mapping
+  const apiPages = projectSettings.getApiPages();
+  const componentToApiMap = new Map<string, string>();
+  
+  for (const apiPage of apiPages) {
+    try {
+      // Extract component name from API filename
+      const apiFilename = path.basename(apiPage.pathname, '.json');
+      const jsonPath = path.join(baseDir, `docs/pages/material-ui/api/${apiFilename}.json`);
+      
+      if (fs.existsSync(jsonPath)) {
+        const apiContent = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+        const componentName = apiContent.name;
+        
+        // Find markdown files that might reference this component
+        for (const componentDir of componentDirs) {
+          // Direct match
+          if (componentDir === apiFilename) {
+            componentToApiMap.set(componentDir, jsonPath);
+            continue;
+          }
+          
+          // Check if this component matches with the API
+          // For plurals like "buttons" -> "button", "chips" -> "chip" etc.
+          if (componentDir === componentName?.toLowerCase() + 's' || 
+              componentDir.replace(/s$/, '') === apiFilename ||
+              componentDir.replace(/-/g, '') === apiFilename.replace(/-/g, '')) {
+            componentToApiMap.set(componentDir, jsonPath);
+          }
+        }
+      }
+    } catch (error) {
+      // Skip invalid API files
+      continue;
+    }
+  }
+  
+  for (const componentName of componentDirs) {
+    // Skip if grep pattern doesn't match
+    if (grep && !grep.test(componentName)) {
+      continue;
+    }
+    
+    // Skip special files
+    if (componentName === 'about-the-lab') {
+      continue;
+    }
+    
+    const markdownPath = path.join(componentsDir, componentName, `${componentName}.md`);
+    
+    // Skip if markdown file doesn't exist
+    if (!fs.existsSync(markdownPath)) {
+      console.warn(`Warning: Markdown file not found for component: ${componentName}`);
+      continue;
+    }
+    
+    const component: ComponentDocInfo = {
+      name: componentName,
+      markdownPath,
+    };
+    
+    // Use the mapped API path if available
+    const apiJsonPath = componentToApiMap.get(componentName);
+    if (apiJsonPath) {
+      component.apiJsonPath = apiJsonPath;
+    }
+    
+    components.push(component);
+  }
+  
+  return components;
+}
+
+/**
+ * Process a single component
+ */
+function processComponent(component: ComponentDocInfo, options: { includeApi: boolean }): string {
+  console.log(`Processing component: ${component.name}`);
+  
+  // Process the markdown file with demo replacement
+  let processedMarkdown = processMarkdownFile(component.markdownPath);
+  
+  // Add API section if JSON exists and includeApi is true
+  if (options.includeApi && component.apiJsonPath) {
+    try {
+      const apiMarkdown = processApiFile(component.apiJsonPath);
+      processedMarkdown += '\n\n' + apiMarkdown;
+    } catch (error) {
+      console.warn(`Warning: Could not process API for ${component.name}:`, error);
+    }
+  }
+  
+  return processedMarkdown;
+}
+
+/**
+ * Main build function
+ */
+async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
+  const grep = argv.grep ? new RegExp(argv.grep) : undefined;
+  const outputDir = argv.outputDir || path.join(process.cwd(), 'llms-docs');
+  const includeApi = argv.includeApi !== false; // Default to true
+  
+  console.log(`Building LLMs docs...`);
+  console.log(`Output directory: ${outputDir}`);
+  console.log(`Include API: ${includeApi}`);
+  if (grep) {
+    console.log(`Filter pattern: ${grep}`);
+  }
+  
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  // Find all components
+  const baseDir = process.cwd();
+  const components = findComponentMarkdownFiles(baseDir, grep);
+  
+  console.log(`Found ${components.length} components to process`);
+  
+  // Process each component
+  for (const component of components) {
+    try {
+      const processedMarkdown = processComponent(component, { includeApi });
+      
+      // Write to output file
+      const outputFileName = `${component.name}.md`;
+      const outputPath = path.join(outputDir, outputFileName);
+      
+      fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
+      console.log(`✓ Generated: ${outputFileName}`);
+    } catch (error) {
+      console.error(`✗ Error processing ${component.name}:`, error);
+    }
+  }
+  
+  console.log(`\nCompleted! Generated ${components.length} files in ${outputDir}`);
+}
+
+/**
+ * CLI setup
+ */
+yargs(process.argv.slice(2))
+  .command({
+    command: '$0',
+    describe: 'Generates LLM-optimized documentation for MUI components.',
+    builder: (command) => {
+      return command
+        .option('grep', {
+          description:
+            'Only generate files for components matching the pattern. The string is treated as a RegExp.',
+          type: 'string',
+        })
+        .option('outputDir', {
+          description: 'Output directory for generated markdown files.',
+          type: 'string',
+          default: './llms-docs',
+        })
+        .option('includeApi', {
+          description: 'Whether to include API documentation at the end of each component doc.',
+          type: 'boolean',
+          default: true,
+        });
+    },
+    handler: buildLlmsDocs,
+  })
+  .help()
+  .strict(true)
+  .version(false)
+  .parse();
\ No newline at end of file
diff --git a/scripts/buildLlmsDocs/tsconfig.json b/scripts/buildLlmsDocs/tsconfig.json
new file mode 100644
index 00000000000000..7feef43854f7fa
--- /dev/null
+++ b/scripts/buildLlmsDocs/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./build",
+    "allowJs": false,
+    "noEmit": false
+  },
+  "include": ["./index.ts"],
+  "exclude": []
+}
\ No newline at end of file

From 8b9bfef60d6b72b674dea2928c3685072762987b Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 09:24:37 +0700
Subject: [PATCH 03/29] wip: simpliify the script

---
 .../joyUi/getJoyUiComponentInfo.ts            |   1 +
 .../materialUi/getMaterialUiComponentInfo.ts  |   1 +
 .../muiSystem/getSystemComponentInfo.ts       |   1 +
 packages/api-docs-builder/index.ts            |   2 +-
 .../api-docs-builder/types/utils.types.ts     |   2 +-
 scripts/buildLlmsDocs/index.ts                | 210 +++++++++---------
 6 files changed, 110 insertions(+), 107 deletions(-)

diff --git a/packages/api-docs-builder-core/joyUi/getJoyUiComponentInfo.ts b/packages/api-docs-builder-core/joyUi/getJoyUiComponentInfo.ts
index f0d84cd52c4b9a..d2358007899f11 100644
--- a/packages/api-docs-builder-core/joyUi/getJoyUiComponentInfo.ts
+++ b/packages/api-docs-builder-core/joyUi/getJoyUiComponentInfo.ts
@@ -60,6 +60,7 @@ export function getJoyUiComponentInfo(filename: string): ComponentInfo {
       return allMarkdowns
         .filter((page) => page.pathname.startsWith('/joy') && page.components.includes(name))
         .map((page) => ({
+          filePath: page.filename, // pathname of the markdown file
           demoPageTitle: getTitle(page.markdownContent),
           demoPathname: fixPathname(page.pathname),
         }));
diff --git a/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.ts b/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.ts
index 3090b60d23053a..91735722c979dd 100644
--- a/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.ts
+++ b/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.ts
@@ -62,6 +62,7 @@ export function getMaterialUiComponentInfo(filename: string): ComponentInfo {
       return allMarkdowns
         .filter((page) => page.pathname.startsWith('/material') && page.components.includes(name))
         .map((page) => ({
+          filePath: page.filename, // pathname of the markdown file
           demoPageTitle: getTitle(page.markdownContent),
           demoPathname: fixPathname(page.pathname),
         }));
diff --git a/packages/api-docs-builder-core/muiSystem/getSystemComponentInfo.ts b/packages/api-docs-builder-core/muiSystem/getSystemComponentInfo.ts
index 4d8b8a580c8424..c6bfffe8ec841d 100644
--- a/packages/api-docs-builder-core/muiSystem/getSystemComponentInfo.ts
+++ b/packages/api-docs-builder-core/muiSystem/getSystemComponentInfo.ts
@@ -76,6 +76,7 @@ export function getSystemComponentInfo(filename: string): ComponentInfo {
       return allMarkdowns
         .filter((page) => page.components.includes(name))
         .map((page) => ({
+          filePath: page.filename, // pathname of the markdown file
           demoPageTitle: pathToSystemTitle({
             ...page,
             title: getTitle(page.markdownContent),
diff --git a/packages/api-docs-builder/index.ts b/packages/api-docs-builder/index.ts
index 5bc030987a977b..f504480f844334 100644
--- a/packages/api-docs-builder/index.ts
+++ b/packages/api-docs-builder/index.ts
@@ -10,4 +10,4 @@ export type {
   HookApiContent,
   ComponentClassDefinition,
 } from './types/ApiBuilder.types';
-export type { Slot } from './types/utils.types';
+export type { Slot, ComponentInfo } from './types/utils.types';
diff --git a/packages/api-docs-builder/types/utils.types.ts b/packages/api-docs-builder/types/utils.types.ts
index 6cd4f256bdd028..58c3c940cee044 100644
--- a/packages/api-docs-builder/types/utils.types.ts
+++ b/packages/api-docs-builder/types/utils.types.ts
@@ -47,7 +47,7 @@ export type ComponentInfo = {
      */
     apiPathname: string;
   };
-  getDemos: () => Array<{ demoPageTitle: string; demoPathname: string }>;
+  getDemos: () => Array<{ demoPageTitle: string; demoPathname: string; filePath: string }>;
   apiPagesDirectory: string;
   /**
    * The path to import specific layout config of the page if needed.
diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index e40fd62776fb53..78227a961da542 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -2,118 +2,104 @@ import * as fs from 'fs';
 import * as path from 'path';
 import yargs, { ArgumentsCamelCase } from 'yargs';
 import { processMarkdownFile, processApiFile } from '@mui/internal-scripts/generate-llms-txt';
-import { getMaterialUiComponentInfo } from '../../packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo';
 import { projectSettings } from '../../packages/api-docs-builder-core/materialUi/projectSettings';
+import { ComponentInfo } from '@mui-internal/api-docs-builder';
+import findComponents from '../../packages/api-docs-builder/utils/findComponents';
 
 interface ComponentDocInfo {
   name: string;
-  markdownPath: string;
+  componentInfo: ComponentInfo;
+  demos: Array<{ demoPageTitle: string; demoPathname: string }>;
+  markdownPath?: string;
   apiJsonPath?: string;
 }
 
-type CommandOptions = { 
-  grep?: string; 
+type CommandOptions = {
+  grep?: string;
   outputDir?: string;
   includeApi?: boolean;
 };
 
 /**
- * Find all component markdown files and map them to API files using the API docs builder
+ * Find all components using the API docs builder infrastructure
  */
-function findComponentMarkdownFiles(baseDir: string, grep?: RegExp): ComponentDocInfo[] {
-  const componentsDir = path.join(baseDir, 'docs/data/material/components');
+async function findComponentsToProcess(grep: RegExp | null): Promise<ComponentDocInfo[]> {
   const components: ComponentDocInfo[] = [];
-  
-  if (!fs.existsSync(componentsDir)) {
-    throw new Error(`Components directory not found: ${componentsDir}`);
-  }
-  
-  const componentDirs = fs.readdirSync(componentsDir, { withFileTypes: true })
-    .filter(dirent => dirent.isDirectory())
-    .map(dirent => dirent.name);
-  
-  // Get all API pages to create a reverse mapping
-  const apiPages = projectSettings.getApiPages();
-  const componentToApiMap = new Map<string, string>();
-  
-  for (const apiPage of apiPages) {
-    try {
-      // Extract component name from API filename
-      const apiFilename = path.basename(apiPage.pathname, '.json');
-      const jsonPath = path.join(baseDir, `docs/pages/material-ui/api/${apiFilename}.json`);
-      
-      if (fs.existsSync(jsonPath)) {
-        const apiContent = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
-        const componentName = apiContent.name;
+
+  // Iterate through TypeScript projects, using the same logic as buildApi.ts
+  for (const project of projectSettings.typeScriptProjects) {
+    const projectComponents = findComponents(path.join(project.rootPath, 'src')).filter(
+      (component) => {
+        if (projectSettings.skipComponent(component.filename)) {
+          return false;
+        }
+
+        if (grep === null) {
+          return true;
+        }
+
+        return grep.test(component.filename);
+      },
+    );
+
+    for (const component of projectComponents) {
+      try {
+        // Get component info using the API docs builder
+        const componentInfo = projectSettings.getComponentInfo(component.filename);
         
-        // Find markdown files that might reference this component
-        for (const componentDir of componentDirs) {
-          // Direct match
-          if (componentDir === apiFilename) {
-            componentToApiMap.set(componentDir, jsonPath);
-            continue;
-          }
-          
-          // Check if this component matches with the API
-          // For plurals like "buttons" -> "button", "chips" -> "chip" etc.
-          if (componentDir === componentName?.toLowerCase() + 's' || 
-              componentDir.replace(/s$/, '') === apiFilename ||
-              componentDir.replace(/-/g, '') === apiFilename.replace(/-/g, '')) {
-            componentToApiMap.set(componentDir, jsonPath);
-          }
+        // Skip if component should be skipped (internal, etc.)
+        const fileInfo = componentInfo.readFile();
+        if (fileInfo.shouldSkip) {
+          continue;
         }
+
+        // Get demos for this component
+        const demos = componentInfo.getDemos();
+        
+        // Skip if no demos found (likely not a public component)
+        if (demos.length === 0) {
+          continue;
+        }
+
+        // Get the markdown file path from the first demo
+        const firstDemo = demos[0];
+        const markdownPath = firstDemo ? firstDemo.filePath : undefined;
+
+        // Get API JSON path
+        const apiJsonPath = path.join(componentInfo.apiPagesDirectory, `${path.basename(componentInfo.apiPathname)}.json`);
+
+        components.push({
+          name: componentInfo.name,
+          componentInfo,
+          demos,
+          markdownPath,
+          apiJsonPath: fs.existsSync(apiJsonPath) ? apiJsonPath : undefined,
+        });
+      } catch (error) {
+        // Skip components that can't be processed
+        continue;
       }
-    } catch (error) {
-      // Skip invalid API files
-      continue;
     }
   }
-  
-  for (const componentName of componentDirs) {
-    // Skip if grep pattern doesn't match
-    if (grep && !grep.test(componentName)) {
-      continue;
-    }
-    
-    // Skip special files
-    if (componentName === 'about-the-lab') {
-      continue;
-    }
-    
-    const markdownPath = path.join(componentsDir, componentName, `${componentName}.md`);
-    
-    // Skip if markdown file doesn't exist
-    if (!fs.existsSync(markdownPath)) {
-      console.warn(`Warning: Markdown file not found for component: ${componentName}`);
-      continue;
-    }
-    
-    const component: ComponentDocInfo = {
-      name: componentName,
-      markdownPath,
-    };
-    
-    // Use the mapped API path if available
-    const apiJsonPath = componentToApiMap.get(componentName);
-    if (apiJsonPath) {
-      component.apiJsonPath = apiJsonPath;
-    }
-    
-    components.push(component);
-  }
-  
+
   return components;
 }
 
 /**
  * Process a single component
  */
-function processComponent(component: ComponentDocInfo, options: { includeApi: boolean }): string {
+function processComponent(component: ComponentDocInfo, options: { includeApi: boolean }): string | null {
   console.log(`Processing component: ${component.name}`);
-  
+
+  // Skip if no markdown file found
+  if (!component.markdownPath) {
+    console.warn(`Warning: No markdown file found for component: ${component.name}`);
+    return null;
+  }
+
   // Process the markdown file with demo replacement
   let processedMarkdown = processMarkdownFile(component.markdownPath);
-  
+
   // Add API section if JSON exists and includeApi is true
   if (options.includeApi && component.apiJsonPath) {
     try {
@@ -123,7 +109,7 @@ function processComponent(component: ComponentDocInfo, options: { includeApi: bo
       console.warn(`Warning: Could not process API for ${component.name}:`, error);
     }
   }
-  
+
   return processedMarkdown;
 }
 
@@ -131,45 +117,59 @@ function processComponent(component: ComponentDocInfo, options: { includeApi: bo
  * Main build function
  */
 async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
-  const grep = argv.grep ? new RegExp(argv.grep) : undefined;
-  const outputDir = argv.outputDir || path.join(process.cwd(), 'llms-docs');
+  const grep = argv.grep ? new RegExp(argv.grep) : null;
+  const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
   const includeApi = argv.includeApi !== false; // Default to true
-  
+
   console.log(`Building LLMs docs...`);
   console.log(`Output directory: ${outputDir}`);
   console.log(`Include API: ${includeApi}`);
   if (grep) {
     console.log(`Filter pattern: ${grep}`);
   }
-  
-  // Ensure output directory exists
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-  
+
   // Find all components
-  const baseDir = process.cwd();
-  const components = findComponentMarkdownFiles(baseDir, grep);
-  
+  const components = await findComponentsToProcess(grep);
+
   console.log(`Found ${components.length} components to process`);
-  
+
   // Process each component
+  let processedCount = 0;
   for (const component of components) {
     try {
       const processedMarkdown = processComponent(component, { includeApi });
       
-      // Write to output file
-      const outputFileName = `${component.name}.md`;
+      if (!processedMarkdown) {
+        continue;
+      }
+
+      // Use the component's demo pathname to create the output structure
+      // e.g., /material-ui/react-accordion/ -> material-ui/react-accordion.md
+      const outputFileName = component.demos[0] ? 
+        component.demos[0].demoPathname
+          .replace(/^\//, '')
+          .replace(/\/$/, '') + '.md' :
+        component.componentInfo.apiPathname
+          .replace(/^\//, '')
+          .replace(/\/$/, '') + '.md';
+
       const outputPath = path.join(outputDir, outputFileName);
-      
+
+      // Ensure the directory exists
+      const outputDirPath = path.dirname(outputPath);
+      if (!fs.existsSync(outputDirPath)) {
+        fs.mkdirSync(outputDirPath, { recursive: true });
+      }
+
       fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
       console.log(`✓ Generated: ${outputFileName}`);
+      processedCount++;
     } catch (error) {
       console.error(`✗ Error processing ${component.name}:`, error);
     }
   }
-  
-  console.log(`\nCompleted! Generated ${components.length} files in ${outputDir}`);
+
+  console.log(`\nCompleted! Generated ${processedCount} files in ${outputDir}`);
 }
 
 /**
@@ -189,7 +189,7 @@ yargs(process.argv.slice(2))
         .option('outputDir', {
           description: 'Output directory for generated markdown files.',
           type: 'string',
-          default: './llms-docs',
+          default: './docs/public',
         })
         .option('includeApi', {
           description: 'Whether to include API documentation at the end of each component doc.',
@@ -202,4 +202,4 @@ yargs(process.argv.slice(2))
   .help()
   .strict(true)
   .version(false)
-  .parse();
\ No newline at end of file
+  .parse();

From 7070b18878cda0854b365c4522382cffe39d293f Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 09:36:13 +0700
Subject: [PATCH 04/29] fix table generation

---
 .../scripts/generate-llms-txt/src/processApi.ts        | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index e3f608e0dbb738..cde1797120388c 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -103,10 +103,14 @@ function formatPropType(prop: ApiProp): string {
   }
   
   if (prop.signature) {
-    type = `\`${prop.signature.type}\``;
+    type = prop.signature.type;
   }
   
-  return type;
+  // Escape pipes in union types for better markdown readability
+  type = type.replace(/\s*\|\s*/g, ' \\| ');
+  
+  // Wrap all prop types in backticks to prevent markdown table issues with pipes
+  return `\`${type}\``;
 }
 
 /**
@@ -125,7 +129,7 @@ function generatePropsTable(props: Record<string, ApiProp>): string {
   for (const [propName, prop] of propEntries) {
     const name = prop.deprecated ? `${propName} (deprecated)` : propName;
     const type = formatPropType(prop);
-    const defaultValue = prop.default ? `\`${prop.default}\`` : '-';
+    const defaultValue = prop.default || '-';
     const required = prop.required ? 'Yes' : 'No';
     
     let description = '';

From 7094df182cb65926a5589a9cf0fdba9469b0bb1f Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 09:43:05 +0700
Subject: [PATCH 05/29] accept project settings from cli

---
 scripts/buildLlmsDocs/index.ts | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 78227a961da542..205faf82715b76 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -2,8 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import yargs, { ArgumentsCamelCase } from 'yargs';
 import { processMarkdownFile, processApiFile } from '@mui/internal-scripts/generate-llms-txt';
-import { projectSettings } from '../../packages/api-docs-builder-core/materialUi/projectSettings';
-import { ComponentInfo } from '@mui-internal/api-docs-builder';
+import { ComponentInfo, ProjectSettings } from '@mui-internal/api-docs-builder';
 import findComponents from '../../packages/api-docs-builder/utils/findComponents';
 
 interface ComponentDocInfo {
@@ -18,12 +17,16 @@ type CommandOptions = {
   grep?: string;
   outputDir?: string;
   includeApi?: boolean;
+  projectSettings?: string;
 };
 
 /**
  * Find all components using the API docs builder infrastructure
  */
-async function findComponentsToProcess(grep: RegExp | null): Promise<ComponentDocInfo[]> {
+async function findComponentsToProcess(
+  projectSettings: ProjectSettings,
+  grep: RegExp | null
+): Promise<ComponentDocInfo[]> {
   const components: ComponentDocInfo[] = [];
 
   // Iterate through TypeScript projects, using the same logic as buildApi.ts
@@ -121,7 +124,22 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
   const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
   const includeApi = argv.includeApi !== false; // Default to true
 
+  // Load project settings from the specified path
+  if (!argv.projectSettings) {
+    throw new Error('--projectSettings is required');
+  }
+
+  let projectSettings: ProjectSettings;
+  try {
+    const settingsPath = path.resolve(argv.projectSettings);
+    const settingsModule = await import(settingsPath);
+    projectSettings = settingsModule.projectSettings || settingsModule.default || settingsModule;
+  } catch (error) {
+    throw new Error(`Failed to load project settings from ${argv.projectSettings}: ${error}`);
+  }
+
   console.log(`Building LLMs docs...`);
+  console.log(`Project settings: ${argv.projectSettings}`);
   console.log(`Output directory: ${outputDir}`);
   console.log(`Include API: ${includeApi}`);
   if (grep) {
@@ -129,7 +147,7 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
   }
 
   // Find all components
-  const components = await findComponentsToProcess(grep);
+  const components = await findComponentsToProcess(projectSettings, grep);
 
   console.log(`Found ${components.length} components to process`);
 
@@ -195,6 +213,11 @@ yargs(process.argv.slice(2))
           description: 'Whether to include API documentation at the end of each component doc.',
           type: 'boolean',
           default: true,
+        })
+        .option('projectSettings', {
+          description: 'Path to the project settings module that exports ProjectSettings interface.',
+          type: 'string',
+          demandOption: true,
         });
     },
     handler: buildLlmsDocs,

From 81838cf9865fa75df77e1297e82f85e6d1fa1883 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 11:51:45 +0700
Subject: [PATCH 06/29] able to process non component markdown

---
 .gitignore                     |  1 +
 scripts/buildLlmsDocs/index.ts | 84 +++++++++++++++++++++++++++++++++-
 2 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index b96f61af23f923..cbad2d4b1882e3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@
 /docs/export
 /docs/pages/playground/
 /docs/public/feed/
+/docs/public/material-ui/
 /examples/**/.cache
 /packages/mui-codemod/lib
 /packages/mui-envinfo/*.tgz
diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 205faf82715b76..fcf01ede55451a 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -3,7 +3,10 @@ import * as path from 'path';
 import yargs, { ArgumentsCamelCase } from 'yargs';
 import { processMarkdownFile, processApiFile } from '@mui/internal-scripts/generate-llms-txt';
 import { ComponentInfo, ProjectSettings } from '@mui-internal/api-docs-builder';
+import { fixPathname } from '../../packages/api-docs-builder/buildApiUtils';
+import replaceUrl from '../../packages/api-docs-builder/utils/replaceUrl';
 import findComponents from '../../packages/api-docs-builder/utils/findComponents';
+import findPagesMarkdown from '../../packages/api-docs-builder/utils/findPagesMarkdown';
 
 interface ComponentDocInfo {
   name: string;
@@ -18,6 +21,7 @@ type CommandOptions = {
   outputDir?: string;
   includeApi?: boolean;
   projectSettings?: string;
+  nonComponentFolders?: string[];
 };
 
 /**
@@ -88,6 +92,48 @@ async function findComponentsToProcess(
   return components;
 }
 
+
+/**
+ * Find all non-component markdown files from specified folders
+ */
+function findNonComponentMarkdownFiles(
+  folders: string[],
+  grep: RegExp | null
+): Array<{ markdownPath: string; outputPath: string }> {
+  // Get all markdown files using the existing findPagesMarkdown utility
+  const allMarkdownFiles = findPagesMarkdown();
+  
+  const files: Array<{ markdownPath: string; outputPath: string }> = [];
+  
+  for (const page of allMarkdownFiles) {
+    // Check if the page belongs to one of the specified folders
+    const belongsToFolder = folders.some(folder => page.pathname.startsWith(`/${folder}`));
+    if (!belongsToFolder) {
+      continue;
+    }
+    
+    // Apply grep filter if specified
+    if (grep) {
+      const fileName = path.basename(page.filename);
+      if (!grep.test(fileName) && !grep.test(page.pathname)) {
+        continue;
+      }
+    }
+    
+    // Apply fixPathname first, then replaceUrl to get the proper output structure (like components)
+    const afterFixPathname = fixPathname(page.pathname);
+    const fixedPathname = replaceUrl(afterFixPathname, '/material-ui/');
+    const outputPath = fixedPathname.replace(/^\//, '').replace(/\/$/, '') + '.md';
+    
+    files.push({
+      markdownPath: page.filename,
+      outputPath,
+    });
+  }
+  
+  return files;
+}
+
 /**
  * Process a single component
  */
@@ -151,6 +197,13 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
 
   console.log(`Found ${components.length} components to process`);
 
+  // Find non-component markdown files if specified
+  let nonComponentFiles: Array<{ markdownPath: string; outputPath: string }> = [];
+  if (argv.nonComponentFolders && argv.nonComponentFolders.length > 0) {
+    nonComponentFiles = findNonComponentMarkdownFiles(argv.nonComponentFolders, grep);
+    console.log(`Found ${nonComponentFiles.length} non-component markdown files to process`);
+  }
+
   // Process each component
   let processedCount = 0;
   for (const component of components) {
@@ -187,6 +240,30 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
     }
   }
 
+  // Process non-component markdown files
+  for (const file of nonComponentFiles) {
+    try {
+      console.log(`Processing non-component file: ${path.relative(process.cwd(), file.markdownPath)}`);
+      
+      // Process the markdown file with demo replacement
+      const processedMarkdown = processMarkdownFile(file.markdownPath);
+      
+      const outputPath = path.join(outputDir, file.outputPath);
+      
+      // Ensure the directory exists
+      const outputDirPath = path.dirname(outputPath);
+      if (!fs.existsSync(outputDirPath)) {
+        fs.mkdirSync(outputDirPath, { recursive: true });
+      }
+      
+      fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
+      console.log(`✓ Generated: ${file.outputPath}`);
+      processedCount++;
+    } catch (error) {
+      console.error(`✗ Error processing ${file.markdownPath}:`, error);
+    }
+  }
+
   console.log(`\nCompleted! Generated ${processedCount} files in ${outputDir}`);
 }
 
@@ -197,7 +274,7 @@ yargs(process.argv.slice(2))
   .command({
     command: '$0',
     describe: 'Generates LLM-optimized documentation for MUI components.',
-    builder: (command) => {
+    builder: (command: any) => {
       return command
         .option('grep', {
           description:
@@ -218,6 +295,11 @@ yargs(process.argv.slice(2))
           description: 'Path to the project settings module that exports ProjectSettings interface.',
           type: 'string',
           demandOption: true,
+        })
+        .option('nonComponentFolders', {
+          description: 'List of folders from docs/data/ to process non-component markdown files.',
+          type: 'array',
+          default: [],
         });
     },
     handler: buildLlmsDocs,

From 02a80c6ffce9784ad2f16ae966ff7b098e711ed8 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 11:55:30 +0700
Subject: [PATCH 07/29] remove includeApi from option

---
 scripts/buildLlmsDocs/index.ts | 71 +++++++++++++++-------------------
 1 file changed, 32 insertions(+), 39 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index fcf01ede55451a..25ba510b0c8837 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -19,7 +19,6 @@ interface ComponentDocInfo {
 type CommandOptions = {
   grep?: string;
   outputDir?: string;
-  includeApi?: boolean;
   projectSettings?: string;
   nonComponentFolders?: string[];
 };
@@ -29,7 +28,7 @@ type CommandOptions = {
  */
 async function findComponentsToProcess(
   projectSettings: ProjectSettings,
-  grep: RegExp | null
+  grep: RegExp | null,
 ): Promise<ComponentDocInfo[]> {
   const components: ComponentDocInfo[] = [];
 
@@ -53,7 +52,7 @@ async function findComponentsToProcess(
       try {
         // Get component info using the API docs builder
         const componentInfo = projectSettings.getComponentInfo(component.filename);
-        
+
         // Skip if component should be skipped (internal, etc.)
         const fileInfo = componentInfo.readFile();
         if (fileInfo.shouldSkip) {
@@ -62,7 +61,7 @@ async function findComponentsToProcess(
 
         // Get demos for this component
         const demos = componentInfo.getDemos();
-        
+
         // Skip if no demos found (likely not a public component)
         if (demos.length === 0) {
           continue;
@@ -73,7 +72,10 @@ async function findComponentsToProcess(
         const markdownPath = firstDemo ? firstDemo.filePath : undefined;
 
         // Get API JSON path
-        const apiJsonPath = path.join(componentInfo.apiPagesDirectory, `${path.basename(componentInfo.apiPathname)}.json`);
+        const apiJsonPath = path.join(
+          componentInfo.apiPagesDirectory,
+          `${path.basename(componentInfo.apiPathname)}.json`,
+        );
 
         components.push({
           name: componentInfo.name,
@@ -92,26 +94,25 @@ async function findComponentsToProcess(
   return components;
 }
 
-
 /**
  * Find all non-component markdown files from specified folders
  */
 function findNonComponentMarkdownFiles(
   folders: string[],
-  grep: RegExp | null
+  grep: RegExp | null,
 ): Array<{ markdownPath: string; outputPath: string }> {
   // Get all markdown files using the existing findPagesMarkdown utility
   const allMarkdownFiles = findPagesMarkdown();
-  
+
   const files: Array<{ markdownPath: string; outputPath: string }> = [];
-  
+
   for (const page of allMarkdownFiles) {
     // Check if the page belongs to one of the specified folders
-    const belongsToFolder = folders.some(folder => page.pathname.startsWith(`/${folder}`));
+    const belongsToFolder = folders.some((folder) => page.pathname.startsWith(`/${folder}`));
     if (!belongsToFolder) {
       continue;
     }
-    
+
     // Apply grep filter if specified
     if (grep) {
       const fileName = path.basename(page.filename);
@@ -119,25 +120,25 @@ function findNonComponentMarkdownFiles(
         continue;
       }
     }
-    
+
     // Apply fixPathname first, then replaceUrl to get the proper output structure (like components)
     const afterFixPathname = fixPathname(page.pathname);
     const fixedPathname = replaceUrl(afterFixPathname, '/material-ui/');
     const outputPath = fixedPathname.replace(/^\//, '').replace(/\/$/, '') + '.md';
-    
+
     files.push({
       markdownPath: page.filename,
       outputPath,
     });
   }
-  
+
   return files;
 }
 
 /**
  * Process a single component
  */
-function processComponent(component: ComponentDocInfo, options: { includeApi: boolean }): string | null {
+function processComponent(component: ComponentDocInfo): string | null {
   console.log(`Processing component: ${component.name}`);
 
   // Skip if no markdown file found
@@ -149,8 +150,8 @@ function processComponent(component: ComponentDocInfo, options: { includeApi: bo
   // Process the markdown file with demo replacement
   let processedMarkdown = processMarkdownFile(component.markdownPath);
 
-  // Add API section if JSON exists and includeApi is true
-  if (options.includeApi && component.apiJsonPath) {
+  // Add API section if JSON exists
+  if (component.apiJsonPath) {
     try {
       const apiMarkdown = processApiFile(component.apiJsonPath);
       processedMarkdown += '\n\n' + apiMarkdown;
@@ -168,7 +169,6 @@ function processComponent(component: ComponentDocInfo, options: { includeApi: bo
 async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
   const grep = argv.grep ? new RegExp(argv.grep) : null;
   const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
-  const includeApi = argv.includeApi !== false; // Default to true
 
   // Load project settings from the specified path
   if (!argv.projectSettings) {
@@ -187,7 +187,6 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
   console.log(`Building LLMs docs...`);
   console.log(`Project settings: ${argv.projectSettings}`);
   console.log(`Output directory: ${outputDir}`);
-  console.log(`Include API: ${includeApi}`);
   if (grep) {
     console.log(`Filter pattern: ${grep}`);
   }
@@ -208,21 +207,17 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
   let processedCount = 0;
   for (const component of components) {
     try {
-      const processedMarkdown = processComponent(component, { includeApi });
-      
+      const processedMarkdown = processComponent(component);
+
       if (!processedMarkdown) {
         continue;
       }
 
       // Use the component's demo pathname to create the output structure
       // e.g., /material-ui/react-accordion/ -> material-ui/react-accordion.md
-      const outputFileName = component.demos[0] ? 
-        component.demos[0].demoPathname
-          .replace(/^\//, '')
-          .replace(/\/$/, '') + '.md' :
-        component.componentInfo.apiPathname
-          .replace(/^\//, '')
-          .replace(/\/$/, '') + '.md';
+      const outputFileName = component.demos[0]
+        ? component.demos[0].demoPathname.replace(/^\//, '').replace(/\/$/, '') + '.md'
+        : component.componentInfo.apiPathname.replace(/^\//, '').replace(/\/$/, '') + '.md';
 
       const outputPath = path.join(outputDir, outputFileName);
 
@@ -243,19 +238,21 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
   // Process non-component markdown files
   for (const file of nonComponentFiles) {
     try {
-      console.log(`Processing non-component file: ${path.relative(process.cwd(), file.markdownPath)}`);
-      
+      console.log(
+        `Processing non-component file: ${path.relative(process.cwd(), file.markdownPath)}`,
+      );
+
       // Process the markdown file with demo replacement
       const processedMarkdown = processMarkdownFile(file.markdownPath);
-      
+
       const outputPath = path.join(outputDir, file.outputPath);
-      
+
       // Ensure the directory exists
       const outputDirPath = path.dirname(outputPath);
       if (!fs.existsSync(outputDirPath)) {
         fs.mkdirSync(outputDirPath, { recursive: true });
       }
-      
+
       fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
       console.log(`✓ Generated: ${file.outputPath}`);
       processedCount++;
@@ -286,13 +283,9 @@ yargs(process.argv.slice(2))
           type: 'string',
           default: './docs/public',
         })
-        .option('includeApi', {
-          description: 'Whether to include API documentation at the end of each component doc.',
-          type: 'boolean',
-          default: true,
-        })
         .option('projectSettings', {
-          description: 'Path to the project settings module that exports ProjectSettings interface.',
+          description:
+            'Path to the project settings module that exports ProjectSettings interface.',
           type: 'string',
           demandOption: true,
         })

From b0def284d627d4e58023f36ab82298f75ddd6bfc Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 11:58:40 +0700
Subject: [PATCH 08/29] add comment to the file

---
 scripts/buildLlmsDocs/index.ts | 49 ++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 25ba510b0c8837..bcf2e4c7ed71b3 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -1,3 +1,52 @@
+/**
+ * LLM Documentation Generator
+ *
+ * This script generates LLM-optimized documentation by processing MUI component markdown files
+ * and non-component documentation files to create comprehensive, standalone documentation.
+ *
+ * ## Main Workflow:
+ *
+ * 1. **Component Processing**:
+ *    - Discovers all components using the API docs builder infrastructure
+ *    - For each component, finds its markdown documentation and API JSON
+ *    - Processes markdown by replacing `{{"demo": "filename.js"}}` syntax with actual code snippets
+ *    - Appends API documentation (props, slots, CSS classes) to the markdown
+ *    - Outputs to files like `material-ui/react-accordion.md`
+ *
+ * 2. **Non-Component Processing** (optional):
+ *    - Processes markdown files from specified folders (e.g., `system`, `material/customization`)
+ *    - Applies the same demo replacement logic
+ *    - Uses URL transformation logic to maintain consistent paths with components
+ *    - Outputs to files like `system/borders.md`, `material-ui/customization/color.md`
+ *
+ * ## Key Features:
+ *
+ * - **Demo Replacement**: Converts `{{"demo": "filename.js"}}` to actual JSX/TSX code snippets
+ * - **API Integration**: Automatically includes component API documentation (props, slots, CSS)
+ * - **Reusable**: Accepts project settings via CLI to work across different repositories
+ * - **Filtering**: Supports grep patterns to process specific components/files
+ * - **Path Consistency**: Uses existing URL transformation logic for consistent output structure
+ *
+ * ## Usage Examples:
+ *
+ * ```bash
+ * # Process all Material UI components
+ * pnpm tsx scripts/buildLlmsDocs/index.ts --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts
+ *
+ * # Process specific components with non-component docs
+ * pnpm tsx scripts/buildLlmsDocs/index.ts \
+ *   --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts \
+ *   --nonComponentFolders system material/customization \
+ *   --grep "Button|borders"
+ * ```
+ *
+ * ## Output Structure:
+ *
+ * - **Components**: `material-ui/react-{component}.md` (e.g., `material-ui/react-button.md`)
+ * - **Customization**: `material-ui/customization/{topic}.md` (e.g., `material-ui/customization/color.md`)
+ * - **Getting Started**: `getting-started/{topic}.md` (e.g., `getting-started/installation.md`)
+ */
+
 import * as fs from 'fs';
 import * as path from 'path';
 import yargs, { ArgumentsCamelCase } from 'yargs';

From a1bba8741d28aa099bb6da3167e9ae4e85761e5f Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 13:12:53 +0700
Subject: [PATCH 09/29] fix htmlToMarkdown to handle proper line break

---
 .../generate-llms-txt/src/processApi.ts       | 42 ++++++++++++-------
 1 file changed, 28 insertions(+), 14 deletions(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index cde1797120388c..ffd2f49f14639d 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -60,7 +60,8 @@ interface ApiJson {
  * Convert HTML to markdown
  */
 function htmlToMarkdown(html: string): string {
-  return html
+  // First pass: decode entities and handle inline elements
+  let markdown = html
     // Decode HTML entities first
     .replace(/&lt;/g, '<')
     .replace(/&gt;/g, '>')
@@ -68,27 +69,40 @@ function htmlToMarkdown(html: string): string {
     .replace(/&#124;/g, '|')
     .replace(/&nbsp;/g, ' ')
     .replace(/&amp;/g, '&')
-    // Convert <br> to space for inline content (not newline for table cells)
-    .replace(/<br\s*\/?>/gi, ' ')
     // Convert <code> to backticks
     .replace(/<code>([^<]+)<\/code>/gi, '`$1`')
     // Convert <a> to markdown links
-    .replace(/<a\s+href="([^"]+)">([^<]+)<\/a>/gi, '[$2]($1)')
-    // Convert <ul> and <li> to markdown lists (only for block content)
-    .replace(/<ul>/gi, '')
-    .replace(/<\/ul>/gi, '')
-    .replace(/<li>/gi, '- ')
-    .replace(/<\/li>/gi, '')
-    // Convert <p> to double newline (only for block content)
-    .replace(/<p>/gi, '\n\n')
+    .replace(/<a\s+href="([^"]+)">([^<]+)<\/a>/gi, '[$2]($1)');
+  
+  // Handle lists - process them as complete units to avoid extra line breaks
+  markdown = markdown.replace(/<ul[^>]*>(.*?)<\/ul>/gis, (match, listContent) => {
+    // Process each list item
+    const items = listContent
+      .split(/<\/li>/)
+      .map(item => item.replace(/<li[^>]*>/, '').trim())
+      .filter(item => item.length > 0)
+      .map(item => '- ' + item)
+      .join('\n');
+    
+    return '\n' + items + '\n';
+  });
+  
+  // Handle other block elements
+  markdown = markdown
+    // Convert <br> to newline
+    .replace(/<br\s*\/?>/gi, '\n')
+    // Convert <p> to double newline
+    .replace(/<p[^>]*>/gi, '\n\n')
     .replace(/<\/p>/gi, '')
     // Remove any remaining HTML tags
     .replace(/<[^>]+>/g, '')
-    // Clean up excessive whitespace and newlines
-    .replace(/\s+/g, ' ')
-    .replace(/\n\s+/g, '\n')
+    // Clean up excessive whitespace (but preserve intentional line breaks)
+    .replace(/[ \t]+/g, ' ')
+    .replace(/ *\n */g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
+  
+  return markdown;
 }
 
 /**

From b90b45cd24371c3fd3148950dd196fe0cd7e7abb Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 13:13:04 +0700
Subject: [PATCH 10/29] generate llms.txt

---
 scripts/buildLlmsDocs/index.ts | 202 +++++++++++++++++++++++++++++++++
 1 file changed, 202 insertions(+)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index bcf2e4c7ed71b3..bb6ca78c49f188 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -56,6 +56,7 @@ import { fixPathname } from '../../packages/api-docs-builder/buildApiUtils';
 import replaceUrl from '../../packages/api-docs-builder/utils/replaceUrl';
 import findComponents from '../../packages/api-docs-builder/utils/findComponents';
 import findPagesMarkdown from '../../packages/api-docs-builder/utils/findPagesMarkdown';
+import { getHeaders } from '@mui/internal-markdown';
 
 interface ComponentDocInfo {
   name: string;
@@ -65,6 +66,14 @@ interface ComponentDocInfo {
   apiJsonPath?: string;
 }
 
+interface GeneratedFile {
+  outputPath: string;
+  title: string;
+  description: string;
+  originalMarkdownPath: string;
+  category: string;
+}
+
 type CommandOptions = {
   grep?: string;
   outputDir?: string;
@@ -143,6 +152,41 @@ async function findComponentsToProcess(
   return components;
 }
 
+/**
+ * Extract title and description from markdown content
+ */
+function extractMarkdownInfo(markdownPath: string): { title: string; description: string } {
+  try {
+    const content = fs.readFileSync(markdownPath, 'utf-8');
+    const headers = getHeaders(content);
+
+    // Get title from frontmatter or first h1
+    const title =
+      headers.title || content.match(/^# (.+)$/m)?.[1] || path.basename(markdownPath, '.md');
+
+    // Extract description from the first paragraph with class="description"
+    const descriptionMatch = content.match(/<p class="description">([^<]+)<\/p>/);
+    let description = '';
+
+    if (descriptionMatch) {
+      description = descriptionMatch[1].trim();
+    } else {
+      // Fallback: get first paragraph after title
+      const paragraphMatch = content.match(/^# .+\n\n(.+?)(?:\n\n|$)/m);
+      if (paragraphMatch) {
+        description = paragraphMatch[1].trim();
+      }
+    }
+
+    return { title, description };
+  } catch (error) {
+    return {
+      title: path.basename(markdownPath, '.md'),
+      description: '',
+    };
+  }
+}
+
 /**
  * Find all non-component markdown files from specified folders
  */
@@ -212,6 +256,94 @@ function processComponent(component: ComponentDocInfo): string | null {
   return processedMarkdown;
 }
 
+/**
+ * Check if a file is a component file by examining its markdown header
+ */
+function checkIfComponentFile(file: GeneratedFile): boolean {
+  try {
+    if (!file.originalMarkdownPath) {
+      return false;
+    }
+
+    const content = fs.readFileSync(file.originalMarkdownPath, 'utf-8');
+    const headers = getHeaders(content);
+
+    // Check if the markdown header contains 'components' field
+    return headers.components && headers.components.length > 0;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Convert kebab-case to Title Case
+ */
+function toTitleCase(kebabCase: string): string {
+  return kebabCase
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Generate llms.txt content for a specific directory
+ */
+function generateLlmsTxt(
+  generatedFiles: GeneratedFile[],
+  projectName: string,
+  baseDir: string,
+): string {
+  // Group files by category
+  const groupedByCategory: Record<string, GeneratedFile[]> = {};
+
+  for (const file of generatedFiles) {
+    const category = file.category;
+    if (!groupedByCategory[category]) {
+      groupedByCategory[category] = [];
+    }
+    groupedByCategory[category].push(file);
+  }
+
+  // Generate content
+  let content = `# ${projectName}\n\n`;
+  content += `This is the documentation for the ${projectName} package.\n`;
+  content += `It contains comprehensive guides, components, and utilities for building user interfaces.\n\n`;
+
+  // Add sections for each category
+  // Sort categories to ensure components appear first
+  const sortedCategories = Object.keys(groupedByCategory).sort((a, b) => {
+    if (a === 'components') return -1;
+    if (b === 'components') return 1;
+    return a.localeCompare(b);
+  });
+
+  for (const category of sortedCategories) {
+    const files = groupedByCategory[category];
+    if (files.length === 0) continue;
+
+    const sectionTitle = toTitleCase(category);
+    content += `## ${sectionTitle}\n\n`;
+
+    // Sort files by title
+    files.sort((a, b) => a.title.localeCompare(b.title));
+
+    for (const file of files) {
+      // Calculate relative path from the baseDir to the file
+      const relativePath = file.outputPath.startsWith(baseDir + '/')
+        ? `./${file.outputPath.substring(baseDir.length + 1)}`
+        : `../${file.outputPath}`;
+      content += `- [${file.title}](${relativePath})`;
+      if (file.description) {
+        content += `: ${file.description}`;
+      }
+      content += '\n';
+    }
+    content += '\n';
+  }
+
+  return content.trim();
+}
+
 /**
  * Main build function
  */
@@ -252,6 +384,9 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
     console.log(`Found ${nonComponentFiles.length} non-component markdown files to process`);
   }
 
+  // Track generated files for llms.txt
+  const generatedFiles: GeneratedFile[] = [];
+
   // Process each component
   let processedCount = 0;
   for (const component of components) {
@@ -279,6 +414,21 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
       console.log(`✓ Generated: ${outputFileName}`);
       processedCount++;
+
+      // Track this file for llms.txt (avoid duplicates for components that share the same markdown file)
+      if (component.markdownPath) {
+        const existingFile = generatedFiles.find((f) => f.outputPath === outputFileName);
+        if (!existingFile) {
+          const { title, description } = extractMarkdownInfo(component.markdownPath);
+          generatedFiles.push({
+            outputPath: outputFileName,
+            title,
+            description,
+            originalMarkdownPath: component.markdownPath,
+            category: 'components',
+          });
+        }
+      }
     } catch (error) {
       console.error(`✗ Error processing ${component.name}:`, error);
     }
@@ -305,11 +455,63 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
       console.log(`✓ Generated: ${file.outputPath}`);
       processedCount++;
+
+      // Track this file for llms.txt
+      const { title, description } = extractMarkdownInfo(file.markdownPath);
+
+      // Extract category from the file path
+      // e.g., "material-ui/customization/color.md" -> "customization"
+      // e.g., "getting-started/installation.md" -> "getting-started"
+      const pathParts = file.outputPath.split('/');
+      const category = pathParts.reverse()[1];
+
+      generatedFiles.push({
+        outputPath: file.outputPath,
+        title,
+        description,
+        originalMarkdownPath: file.markdownPath,
+        category,
+      });
     } catch (error) {
       console.error(`✗ Error processing ${file.markdownPath}:`, error);
     }
   }
 
+  // Generate llms.txt files
+  if (generatedFiles.length > 0) {
+    const groupedByFirstDir: Record<string, GeneratedFile[]> = {};
+
+    for (const file of generatedFiles) {
+      const firstDir = file.outputPath.split('/')[0];
+      if (!groupedByFirstDir[firstDir]) {
+        groupedByFirstDir[firstDir] = [];
+      }
+      groupedByFirstDir[firstDir].push(file);
+    }
+
+    for (const [dirName, files] of Object.entries(groupedByFirstDir)) {
+      const projectName =
+        dirName === 'material-ui'
+          ? 'Material UI'
+          : dirName === 'system'
+            ? 'MUI System'
+            : dirName.charAt(0).toUpperCase() + dirName.slice(1);
+
+      const llmsContent = generateLlmsTxt(files, projectName, dirName);
+      const llmsPath = path.join(outputDir, dirName, 'llms.txt');
+
+      // Ensure directory exists
+      const llmsDirPath = path.dirname(llmsPath);
+      if (!fs.existsSync(llmsDirPath)) {
+        fs.mkdirSync(llmsDirPath, { recursive: true });
+      }
+
+      fs.writeFileSync(llmsPath, llmsContent, 'utf-8');
+      console.log(`✓ Generated: ${dirName}/llms.txt`);
+      processedCount++;
+    }
+  }
+
   console.log(`\nCompleted! Generated ${processedCount} files in ${outputDir}`);
 }
 

From b109ced376a65c11269a247915ce6eb6c3a9e14e Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 13:16:07 +0700
Subject: [PATCH 11/29] update comment

---
 scripts/buildLlmsDocs/index.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index bb6ca78c49f188..591d61cf28c5d1 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -19,6 +19,12 @@
  *    - Uses URL transformation logic to maintain consistent paths with components
  *    - Outputs to files like `system/borders.md`, `material-ui/customization/color.md`
  *
+ * 3. **Index Generation** (llms.txt):
+ *    - Generates `llms.txt` index files for each top-level directory
+ *    - Groups files by category (components, customization, getting-started, etc.)
+ *    - Creates markdown-formatted lists with relative paths and descriptions
+ *    - Outputs to files like `material-ui/llms.txt`, `system/llms.txt`
+ *
  * ## Key Features:
  *
  * - **Demo Replacement**: Converts `{{"demo": "filename.js"}}` to actual JSX/TSX code snippets
@@ -26,6 +32,7 @@
  * - **Reusable**: Accepts project settings via CLI to work across different repositories
  * - **Filtering**: Supports grep patterns to process specific components/files
  * - **Path Consistency**: Uses existing URL transformation logic for consistent output structure
+ * - **Auto-indexing**: Generates llms.txt files with categorized documentation listings
  *
  * ## Usage Examples:
  *
@@ -44,7 +51,8 @@
  *
  * - **Components**: `material-ui/react-{component}.md` (e.g., `material-ui/react-button.md`)
  * - **Customization**: `material-ui/customization/{topic}.md` (e.g., `material-ui/customization/color.md`)
- * - **Getting Started**: `getting-started/{topic}.md` (e.g., `getting-started/installation.md`)
+ * - **Getting Started**: `material-ui/getting-started/{topic}.md` (e.g., `material-ui/getting-started/installation.md`)
+ * - **Index Files**: `{directory}/llms.txt` (e.g., `material-ui/llms.txt`, `system/llms.txt`)
  */
 
 import * as fs from 'fs';

From c4062fc9839dbbb3970b27099fd3defe7411ea2f Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 13:16:19 +0700
Subject: [PATCH 12/29] add script to build llms before docs

---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 9ec009f3e3f076..fc4a8930532a4a 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,8 @@
     "release:pack": "tsx scripts/releasePack.mts",
     "docs:api": "rimraf --glob ./docs/pages/**/api-docs ./docs/pages/**/api && pnpm docs:api:build",
     "docs:api:build": "tsx ./scripts/buidApiDocs/index.ts",
-    "docs:build": "pnpm --filter docs build",
+    "docs:llms:build": "tsx ./scripts/buildLlmsDocs/index.ts --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts",
+    "docs:build": "pnpm docs:llms:build && pnpm --filter docs build",
     "docs:build-sw": "pnpm --filter docs build-sw",
     "docs:build-color-preview": "babel-node scripts/buildColorTypes",
     "docs:deploy": "pnpm --filter docs run deploy",

From 7bb07a8cd619da8702c104659f12052df431528d Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 13:23:52 +0700
Subject: [PATCH 13/29] run prettier

---
 .../scripts/generate-llms-txt/src/index.ts    |   2 +-
 .../generate-llms-txt/src/processApi.ts       |  48 +++----
 .../generate-llms-txt/src/processComponent.ts |  45 +++----
 .../generate-llms-txt/test/processApi.test.ts | 121 ++++++++++--------
 .../test/processComponent.test.ts             |  26 ++--
 scripts/buildLlmsDocs/tsconfig.json           |   2 +-
 6 files changed, 133 insertions(+), 111 deletions(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/index.ts b/packages-internal/scripts/generate-llms-txt/src/index.ts
index 85d2b6af02fe09..e1aed7f312a8c9 100644
--- a/packages-internal/scripts/generate-llms-txt/src/index.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/index.ts
@@ -1,3 +1,3 @@
 // Export all functions from both modules
 export * from './processComponent';
-export * from './processApi';
\ No newline at end of file
+export * from './processApi';
diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index ffd2f49f14639d..27aecc2955c76d 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -73,20 +73,20 @@ function htmlToMarkdown(html: string): string {
     .replace(/<code>([^<]+)<\/code>/gi, '`$1`')
     // Convert <a> to markdown links
     .replace(/<a\s+href="([^"]+)">([^<]+)<\/a>/gi, '[$2]($1)');
-  
+
   // Handle lists - process them as complete units to avoid extra line breaks
   markdown = markdown.replace(/<ul[^>]*>(.*?)<\/ul>/gis, (match, listContent) => {
     // Process each list item
     const items = listContent
       .split(/<\/li>/)
-      .map(item => item.replace(/<li[^>]*>/, '').trim())
-      .filter(item => item.length > 0)
-      .map(item => '- ' + item)
+      .map((item) => item.replace(/<li[^>]*>/, '').trim())
+      .filter((item) => item.length > 0)
+      .map((item) => '- ' + item)
       .join('\n');
-    
+
     return '\n' + items + '\n';
   });
-  
+
   // Handle other block elements
   markdown = markdown
     // Convert <br> to newline
@@ -101,7 +101,7 @@ function htmlToMarkdown(html: string): string {
     .replace(/ *\n */g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
-  
+
   return markdown;
 }
 
@@ -110,19 +110,19 @@ function htmlToMarkdown(html: string): string {
  */
 function formatPropType(prop: ApiProp): string {
   let type = prop.type.name;
-  
+
   if (prop.type.description) {
     // Clean up the description
     type = htmlToMarkdown(prop.type.description);
   }
-  
+
   if (prop.signature) {
     type = prop.signature.type;
   }
-  
+
   // Escape pipes in union types for better markdown readability
   type = type.replace(/\s*\|\s*/g, ' \\| ');
-  
+
   // Wrap all prop types in backticks to prevent markdown table issues with pipes
   return `\`${type}\``;
 }
@@ -145,14 +145,15 @@ function generatePropsTable(props: Record<string, ApiProp>): string {
     const type = formatPropType(prop);
     const defaultValue = prop.default || '-';
     const required = prop.required ? 'Yes' : 'No';
-    
+
     let description = '';
     if (prop.deprecated && prop.deprecationInfo) {
       description = `⚠️ ${htmlToMarkdown(prop.deprecationInfo)}`;
     } else if (prop.additionalInfo?.cssApi) {
       description = 'Override or extend the styles applied to the component.';
     } else if (prop.additionalInfo?.sx) {
-      description = 'The system prop that allows defining system overrides as well as additional CSS styles.';
+      description =
+        'The system prop that allows defining system overrides as well as additional CSS styles.';
     }
 
     table += `| ${name} | ${type} | ${defaultValue} | ${required} | ${description} |\n`;
@@ -210,20 +211,22 @@ function generateClassesTable(classes: ApiClass[]): string {
  */
 export function processApiJson(apiJson: ApiJson | string): string {
   const api: ApiJson = typeof apiJson === 'string' ? JSON.parse(apiJson) : apiJson;
-  
+
   let markdown = `# ${api.name} API\n\n`;
 
   // Add deprecation warning if applicable
   if (api.deprecated) {
-    const warningText = api.deprecationInfo ? htmlToMarkdown(api.deprecationInfo) : 
-      'This component is deprecated. Consider using an alternative component.';
+    const warningText = api.deprecationInfo
+      ? htmlToMarkdown(api.deprecationInfo)
+      : 'This component is deprecated. Consider using an alternative component.';
     markdown += `> ⚠️ **Warning**: ${warningText}\n\n`;
   }
 
   // Add demos section
   if (api.demos) {
     markdown += '## Demos\n\n';
-    markdown += 'For examples and details on the usage of this React component, visit the component demo pages:\n\n';
+    markdown +=
+      'For examples and details on the usage of this React component, visit the component demo pages:\n\n';
     markdown += htmlToMarkdown(api.demos) + '\n\n';
   }
 
@@ -248,9 +251,9 @@ export function processApiJson(apiJson: ApiJson | string): string {
 
   // Add spread information
   if (api.spread) {
-    const spreadElement = api.inheritance ? 
-      `[${api.inheritance.component}](${api.inheritance.pathname})` : 
-      'native element';
+    const spreadElement = api.inheritance
+      ? `[${api.inheritance.component}](${api.inheritance.pathname})`
+      : 'native element';
     markdown += `> Any other props supplied will be provided to the root element (${spreadElement}).\n\n`;
   }
 
@@ -259,7 +262,8 @@ export function processApiJson(apiJson: ApiJson | string): string {
     markdown += '## Inheritance\n\n';
     markdown += `While not explicitly documented above, the props of the [${api.inheritance.component}](${api.inheritance.pathname}) component are also available on ${api.name}.`;
     if (api.inheritance.component === 'Transition') {
-      markdown += ' A subset of components support [react-transition-group](https://reactcommunity.org/react-transition-group/transition/) out of the box.';
+      markdown +=
+        ' A subset of components support [react-transition-group](https://reactcommunity.org/react-transition-group/transition/) out of the box.';
     }
     markdown += '\n\n';
   }
@@ -303,4 +307,4 @@ export function processApiJson(apiJson: ApiJson | string): string {
 export function processApiFile(filePath: string): string {
   const content = fs.readFileSync(filePath, 'utf-8');
   return processApiJson(content);
-}
\ No newline at end of file
+}
diff --git a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
index c4ab2ec042f715..51480be06d4ff9 100755
--- a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
@@ -16,39 +16,39 @@ interface DemoReplaceOptions {
 export function replaceDemoWithSnippet(
   markdownContent: string,
   markdownPath: string,
-  options: DemoReplaceOptions = {}
+  options: DemoReplaceOptions = {},
 ): string {
   const { basePath = '', includeTypeScript = true } = options;
-  
+
   // Regular expression to match {{"demo": "filename.js"}} pattern
   const demoRegex = /\{\{"demo":\s*"([^"]+)"(?:,\s*[^}]+)?\}\}/g;
-  
+
   return markdownContent.replace(demoRegex, (match, filename) => {
     try {
       // Extract the base filename without extension
       const baseFilename = filename.replace(/\.(js|tsx?)$/, '');
-      
+
       // Get the directory of the markdown file
       const markdownDir = path.dirname(markdownPath);
-      
+
       let codeSnippet = '';
-      
+
       // Try to read JavaScript file
-      const jsPath = basePath ? 
-        path.join(basePath, `${baseFilename}.js`) : 
-        path.join(markdownDir, `${baseFilename}.js`);
-        
+      const jsPath = basePath
+        ? path.join(basePath, `${baseFilename}.js`)
+        : path.join(markdownDir, `${baseFilename}.js`);
+
       if (fs.existsSync(jsPath)) {
         const jsContent = fs.readFileSync(jsPath, 'utf-8');
         codeSnippet += `\`\`\`jsx\n${jsContent}\n\`\`\``;
       }
-      
+
       // Try to read TypeScript file if includeTypeScript is true
       if (includeTypeScript) {
-        const tsPath = basePath ? 
-          path.join(basePath, `${baseFilename}.tsx`) : 
-          path.join(markdownDir, `${baseFilename}.tsx`);
-          
+        const tsPath = basePath
+          ? path.join(basePath, `${baseFilename}.tsx`)
+          : path.join(markdownDir, `${baseFilename}.tsx`);
+
         if (fs.existsSync(tsPath)) {
           const tsContent = fs.readFileSync(tsPath, 'utf-8');
           if (codeSnippet) {
@@ -57,13 +57,13 @@ export function replaceDemoWithSnippet(
           codeSnippet += `\`\`\`tsx\n${tsContent}\n\`\`\``;
         }
       }
-      
+
       // If no files found, return original match
       if (!codeSnippet) {
         console.warn(`Demo file not found: ${filename}`);
         return match;
       }
-      
+
       return codeSnippet;
     } catch (error) {
       console.error(`Error processing demo ${filename}:`, error);
@@ -78,18 +78,15 @@ export function replaceDemoWithSnippet(
  * @param options - Options for parsing
  * @returns The processed markdown content
  */
-export function processMarkdownFile(
-  filePath: string,
-  options: DemoReplaceOptions = {}
-): string {
+export function processMarkdownFile(filePath: string, options: DemoReplaceOptions = {}): string {
   const content = fs.readFileSync(filePath, 'utf-8');
   const dir = path.dirname(filePath);
-  
+
   // Set basePath relative to markdown file location if not provided
   const processOptions = {
     ...options,
     basePath: options.basePath || dir,
   };
-  
+
   return replaceDemoWithSnippet(content, filePath, processOptions);
-}
\ No newline at end of file
+}
diff --git a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
index 8ca4754f76d56f..d0720b02e51e5c 100644
--- a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
+++ b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
@@ -11,20 +11,20 @@ describe('processApi', () => {
         name: 'Button',
         imports: [
           "import Button from '@mui/material/Button';",
-          "import { Button } from '@mui/material';"
+          "import { Button } from '@mui/material';",
         ],
         props: {
           color: {
             type: { name: 'string' },
             default: "'primary'",
-            required: false
+            required: false,
           },
           disabled: {
             type: { name: 'bool' },
             default: 'false',
-            required: false
-          }
-        }
+            required: false,
+          },
+        },
       };
 
       const result = processApiJson(apiJson);
@@ -33,7 +33,7 @@ describe('processApi', () => {
       expect(result).to.include('## Import');
       expect(result).to.include("import Button from '@mui/material/Button';");
       expect(result).to.include('## Props');
-      expect(result).to.include('| color | string | `\'primary\'` | No |');
+      expect(result).to.include("| color | string | `'primary'` | No |");
       expect(result).to.include('| disabled | bool | `false` | No |');
     });
 
@@ -43,7 +43,7 @@ describe('processApi', () => {
         imports: ["import DeprecatedComponent from '@mui/material/DeprecatedComponent';"],
         props: {},
         deprecated: true,
-        deprecationInfo: 'Use <code>NewComponent</code> instead.'
+        deprecationInfo: 'Use <code>NewComponent</code> instead.',
       };
 
       const result = processApiJson(apiJson);
@@ -59,9 +59,9 @@ describe('processApi', () => {
           oldProp: {
             type: { name: 'string' },
             deprecated: true,
-            deprecationInfo: 'Use <code>newProp</code> instead.'
-          }
-        }
+            deprecationInfo: 'Use <code>newProp</code> instead.',
+          },
+        },
       };
 
       const result = processApiJson(apiJson);
@@ -79,23 +79,24 @@ describe('processApi', () => {
             type: { name: 'func' },
             signature: {
               type: 'function(event: React.SyntheticEvent, value: number) => void',
-              describedArgs: ['event', 'value']
-            }
+              describedArgs: ['event', 'value'],
+            },
           },
           slots: {
             type: {
               name: 'shape',
-              description: '{ root?: elementType, icon?: elementType }'
-            }
+              description: '{ root?: elementType, icon?: elementType }',
+            },
           },
           sx: {
             type: {
               name: 'union',
-              description: 'Array&lt;func<br>&#124;&nbsp;object&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object'
+              description:
+                'Array&lt;func<br>&#124;&nbsp;object&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object',
             },
-            additionalInfo: { sx: true }
-          }
-        }
+            additionalInfo: { sx: true },
+          },
+        },
       };
 
       const result = processApiJson(apiJson);
@@ -111,7 +112,7 @@ describe('processApi', () => {
         name: 'Accordion',
         imports: ["import Accordion from '@mui/material/Accordion';"],
         props: {},
-        demos: '<ul><li><a href="/material-ui/react-accordion/">Accordion</a></li></ul>'
+        demos: '<ul><li><a href="/material-ui/react-accordion/">Accordion</a></li></ul>',
       };
 
       const result = processApiJson(apiJson);
@@ -130,21 +131,23 @@ describe('processApi', () => {
             name: 'root',
             description: 'The component that renders the root.',
             default: 'Paper',
-            class: 'MuiComponent-root'
+            class: 'MuiComponent-root',
           },
           {
             name: 'icon',
             description: 'The icon element.',
             default: 'svg',
-            class: null
-          }
-        ]
+            class: null,
+          },
+        ],
       };
 
       const result = processApiJson(apiJson);
 
       expect(result).to.include('## Slots');
-      expect(result).to.include('| root | `Paper` | `.MuiComponent-root` | The component that renders the root. |');
+      expect(result).to.include(
+        '| root | `Paper` | `.MuiComponent-root` | The component that renders the root. |',
+      );
       expect(result).to.include('| icon | `svg` | - | The icon element. |');
     });
 
@@ -158,22 +161,24 @@ describe('processApi', () => {
             key: 'disabled',
             className: 'Mui-disabled',
             description: 'State class applied to the root element if `disabled={true}`.',
-            isGlobal: true
+            isGlobal: true,
           },
           {
             key: 'root',
             className: 'MuiComponent-root',
             description: 'Styles applied to the root element.',
-            isGlobal: false
-          }
-        ]
+            isGlobal: false,
+          },
+        ],
       };
 
       const result = processApiJson(apiJson);
 
       expect(result).to.include('## CSS');
       expect(result).to.include('### Rule name');
-      expect(result).to.include('| `.Mui-disabled` | - | State class applied to the root element if `disabled={true}`. |');
+      expect(result).to.include(
+        '| `.Mui-disabled` | - | State class applied to the root element if `disabled={true}`. |',
+      );
       expect(result).to.include('| - | root | Styles applied to the root element. |');
     });
 
@@ -184,15 +189,17 @@ describe('processApi', () => {
         props: {},
         inheritance: {
           component: 'Paper',
-          pathname: '/material-ui/api/paper/'
-        }
+          pathname: '/material-ui/api/paper/',
+        },
       };
 
       const result = processApiJson(apiJson);
 
       expect(result).to.include('## Inheritance');
       expect(result).to.include('[Paper](/material-ui/api/paper/)');
-      expect(result).to.include('the props of the [Paper](/material-ui/api/paper/) component are also available on Accordion');
+      expect(result).to.include(
+        'the props of the [Paper](/material-ui/api/paper/) component are also available on Accordion',
+      );
     });
 
     it('should handle spread props', () => {
@@ -203,13 +210,15 @@ describe('processApi', () => {
         spread: true,
         inheritance: {
           component: 'Paper',
-          pathname: '/material-ui/api/paper/'
-        }
+          pathname: '/material-ui/api/paper/',
+        },
       };
 
       const result = processApiJson(apiJson);
 
-      expect(result).to.include('Any other props supplied will be provided to the root element ([Paper](/material-ui/api/paper/))');
+      expect(result).to.include(
+        'Any other props supplied will be provided to the root element ([Paper](/material-ui/api/paper/))',
+      );
     });
 
     it('should handle ref forwarding', () => {
@@ -217,7 +226,7 @@ describe('processApi', () => {
         name: 'Component',
         imports: ["import Component from '@mui/material/Component';"],
         props: {},
-        forwardsRefTo: 'HTMLDivElement'
+        forwardsRefTo: 'HTMLDivElement',
       };
 
       const result = processApiJson(apiJson);
@@ -230,7 +239,7 @@ describe('processApi', () => {
         name: 'Component',
         imports: ["import Component from '@mui/material/Component';"],
         props: {},
-        forwardsRefTo: null
+        forwardsRefTo: null,
       };
 
       const result = processApiJson(apiJson);
@@ -244,7 +253,7 @@ describe('processApi', () => {
         imports: ["import Button from '@mui/material/Button';"],
         props: {},
         themeDefaultProps: true,
-        muiName: 'MuiButton'
+        muiName: 'MuiButton',
       };
 
       const result = processApiJson(apiJson);
@@ -258,12 +267,14 @@ describe('processApi', () => {
         name: 'Box',
         imports: ["import Box from '@mui/material/Box';"],
         props: {},
-        cssComponent: true
+        cssComponent: true,
       };
 
       const result = processApiJson(apiJson);
 
-      expect(result).to.include('As a CSS utility, the `Box` component also supports all system properties');
+      expect(result).to.include(
+        'As a CSS utility, the `Box` component also supports all system properties',
+      );
     });
 
     it('should handle source code section', () => {
@@ -271,13 +282,15 @@ describe('processApi', () => {
         name: 'Component',
         imports: ["import Component from '@mui/material/Component';"],
         props: {},
-        filename: '/packages/mui-material/src/Component/Component.js'
+        filename: '/packages/mui-material/src/Component/Component.js',
       };
 
       const result = processApiJson(apiJson);
 
       expect(result).to.include('## Source code');
-      expect(result).to.include('https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/Component/Component.js');
+      expect(result).to.include(
+        'https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/Component/Component.js',
+      );
     });
 
     it('should handle required props', () => {
@@ -287,13 +300,13 @@ describe('processApi', () => {
         props: {
           children: {
             type: { name: 'node' },
-            required: true
+            required: true,
           },
           optional: {
             type: { name: 'string' },
-            required: false
-          }
-        }
+            required: false,
+          },
+        },
       };
 
       const result = processApiJson(apiJson);
@@ -321,9 +334,9 @@ describe('processApi', () => {
         props: {
           test: {
             type: { name: 'bool' },
-            default: 'true'
-          }
-        }
+            default: 'true',
+          },
+        },
       };
 
       const filePath = path.join(tempDir, 'test-component.json');
@@ -345,11 +358,11 @@ describe('processApi', () => {
           complexProp: {
             type: {
               name: 'union',
-              description: 'Array&lt;func<br>&#124;&nbsp;object&gt;<br>&#124;&nbsp;func'
-            }
-          }
+              description: 'Array&lt;func<br>&#124;&nbsp;object&gt;<br>&#124;&nbsp;func',
+            },
+          },
         },
-        demos: '<p>Test paragraph</p><ul><li>Item 1</li><li>Item 2</li></ul>'
+        demos: '<p>Test paragraph</p><ul><li>Item 1</li><li>Item 2</li></ul>',
       };
 
       const result = processApiJson(apiJson);
@@ -360,4 +373,4 @@ describe('processApi', () => {
       expect(result).to.include('- Item 2');
     });
   });
-});
\ No newline at end of file
+});
diff --git a/packages-internal/scripts/generate-llms-txt/test/processComponent.test.ts b/packages-internal/scripts/generate-llms-txt/test/processComponent.test.ts
index 062068c86b8462..bef716cbf65b4a 100644
--- a/packages-internal/scripts/generate-llms-txt/test/processComponent.test.ts
+++ b/packages-internal/scripts/generate-llms-txt/test/processComponent.test.ts
@@ -36,7 +36,9 @@ export default function BasicButton() {
       // Create test files
       fs.writeFileSync(path.join(tempDir, 'BasicButton.js'), jsContent);
 
-      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), {
+        basePath: tempDir,
+      });
 
       expect(result).to.include('```jsx');
       expect(result).to.include(jsContent);
@@ -52,9 +54,9 @@ export default function BasicButton() {
       fs.writeFileSync(path.join(tempDir, 'Component.js'), jsContent);
       fs.writeFileSync(path.join(tempDir, 'Component.tsx'), tsContent);
 
-      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { 
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), {
         basePath: tempDir,
-        includeTypeScript: true 
+        includeTypeScript: true,
       });
 
       expect(result).to.include('```jsx');
@@ -72,9 +74,9 @@ export default function BasicButton() {
       fs.writeFileSync(path.join(tempDir, 'Component.js'), jsContent);
       fs.writeFileSync(path.join(tempDir, 'Component.tsx'), tsContent);
 
-      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { 
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), {
         basePath: tempDir,
-        includeTypeScript: false 
+        includeTypeScript: false,
       });
 
       expect(result).to.include('```jsx');
@@ -95,7 +97,9 @@ Some text in between.
       fs.writeFileSync(path.join(tempDir, 'First.js'), 'First component');
       fs.writeFileSync(path.join(tempDir, 'Second.js'), 'Second component');
 
-      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), {
+        basePath: tempDir,
+      });
 
       expect(result).to.include('First component');
       expect(result).to.include('Second component');
@@ -105,7 +109,9 @@ Some text in between.
     it('should return original match when demo file is not found', () => {
       const markdown = `{{"demo": "NonExistent.js"}}`;
 
-      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), {
+        basePath: tempDir,
+      });
 
       expect(result).to.equal(markdown);
     });
@@ -115,7 +121,9 @@ Some text in between.
 
       fs.writeFileSync(path.join(tempDir, 'Button.js'), 'Button code');
 
-      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), { basePath: tempDir });
+      const result = replaceDemoWithSnippet(markdown, path.join(tempDir, 'test.md'), {
+        basePath: tempDir,
+      });
 
       expect(result).to.include('```jsx');
       expect(result).to.include('Button code');
@@ -153,4 +161,4 @@ Some text in between.
       expect(result).to.include('Button component');
     });
   });
-});
\ No newline at end of file
+});
diff --git a/scripts/buildLlmsDocs/tsconfig.json b/scripts/buildLlmsDocs/tsconfig.json
index 7feef43854f7fa..2b56dc8d607113 100644
--- a/scripts/buildLlmsDocs/tsconfig.json
+++ b/scripts/buildLlmsDocs/tsconfig.json
@@ -7,4 +7,4 @@
   },
   "include": ["./index.ts"],
   "exclude": []
-}
\ No newline at end of file
+}

From 5aed49dff5965a0b25f444446c4a20040897cdbd Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 14:36:41 +0700
Subject: [PATCH 14/29] fix lint

---
 .../generate-llms-txt/src/processApi.ts       | 12 +--
 scripts/buildLlmsDocs/index.ts                | 98 ++++++++-----------
 2 files changed, 49 insertions(+), 61 deletions(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index 27aecc2955c76d..21d092950fd3b2 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -81,10 +81,10 @@ function htmlToMarkdown(html: string): string {
       .split(/<\/li>/)
       .map((item) => item.replace(/<li[^>]*>/, '').trim())
       .filter((item) => item.length > 0)
-      .map((item) => '- ' + item)
+      .map((item) => `- ${item}`)
       .join('\n');
 
-    return '\n' + items + '\n';
+    return `\n${items}\n`;
   });
 
   // Handle other block elements
@@ -227,7 +227,7 @@ export function processApiJson(apiJson: ApiJson | string): string {
     markdown += '## Demos\n\n';
     markdown +=
       'For examples and details on the usage of this React component, visit the component demo pages:\n\n';
-    markdown += htmlToMarkdown(api.demos) + '\n\n';
+    markdown += `${htmlToMarkdown(api.demos)}\n\n`;
   }
 
   // Add import section
@@ -239,7 +239,7 @@ export function processApiJson(apiJson: ApiJson | string): string {
   // Add props section
   const propsTable = generatePropsTable(api.props);
   if (propsTable) {
-    markdown += propsTable + '\n';
+    markdown += `${propsTable}\n`;
   }
 
   // Add ref information
@@ -277,13 +277,13 @@ export function processApiJson(apiJson: ApiJson | string): string {
   // Add slots section
   const slotsTable = generateSlotsTable(api.slots || []);
   if (slotsTable) {
-    markdown += slotsTable + '\n';
+    markdown += `${slotsTable}\n`;
   }
 
   // Add classes section
   const classesTable = generateClassesTable(api.classes || []);
   if (classesTable) {
-    markdown += classesTable + '\n';
+    markdown += `${classesTable}\n`;
   }
 
   // Add CSS component note
diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 591d61cf28c5d1..56c8f9c370aa41 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -60,11 +60,11 @@ import * as path from 'path';
 import yargs, { ArgumentsCamelCase } from 'yargs';
 import { processMarkdownFile, processApiFile } from '@mui/internal-scripts/generate-llms-txt';
 import { ComponentInfo, ProjectSettings } from '@mui-internal/api-docs-builder';
-import { fixPathname } from '../../packages/api-docs-builder/buildApiUtils';
-import replaceUrl from '../../packages/api-docs-builder/utils/replaceUrl';
-import findComponents from '../../packages/api-docs-builder/utils/findComponents';
-import findPagesMarkdown from '../../packages/api-docs-builder/utils/findPagesMarkdown';
 import { getHeaders } from '@mui/internal-markdown';
+import { fixPathname } from '@mui-internal/api-docs-builder/buildApiUtils';
+import replaceUrl from '@mui-internal/api-docs-builder/utils/replaceUrl';
+import findComponents from '@mui-internal/api-docs-builder/utils/findComponents';
+import findPagesMarkdown from '@mui-internal/api-docs-builder/utils/findPagesMarkdown';
 
 interface ComponentDocInfo {
   name: string;
@@ -225,7 +225,7 @@ function findNonComponentMarkdownFiles(
     // Apply fixPathname first, then replaceUrl to get the proper output structure (like components)
     const afterFixPathname = fixPathname(page.pathname);
     const fixedPathname = replaceUrl(afterFixPathname, '/material-ui/');
-    const outputPath = fixedPathname.replace(/^\//, '').replace(/\/$/, '') + '.md';
+    const outputPath = `${fixedPathname.replace(/^\//, '').replace(/\/$/, '')}.md`;
 
     files.push({
       markdownPath: page.filename,
@@ -240,11 +240,11 @@ function findNonComponentMarkdownFiles(
  * Process a single component
  */
 function processComponent(component: ComponentDocInfo): string | null {
-  console.log(`Processing component: ${component.name}`);
+  // Processing component: ${component.name}
 
   // Skip if no markdown file found
   if (!component.markdownPath) {
-    console.warn(`Warning: No markdown file found for component: ${component.name}`);
+    console.error(`Warning: No markdown file found for component: ${component.name}`);
     return null;
   }
 
@@ -255,34 +255,15 @@ function processComponent(component: ComponentDocInfo): string | null {
   if (component.apiJsonPath) {
     try {
       const apiMarkdown = processApiFile(component.apiJsonPath);
-      processedMarkdown += '\n\n' + apiMarkdown;
+      processedMarkdown += `\n\n${apiMarkdown}`;
     } catch (error) {
-      console.warn(`Warning: Could not process API for ${component.name}:`, error);
+      console.error(`Warning: Could not process API for ${component.name}:`, error);
     }
   }
 
   return processedMarkdown;
 }
 
-/**
- * Check if a file is a component file by examining its markdown header
- */
-function checkIfComponentFile(file: GeneratedFile): boolean {
-  try {
-    if (!file.originalMarkdownPath) {
-      return false;
-    }
-
-    const content = fs.readFileSync(file.originalMarkdownPath, 'utf-8');
-    const headers = getHeaders(content);
-
-    // Check if the markdown header contains 'components' field
-    return headers.components && headers.components.length > 0;
-  } catch (error) {
-    return false;
-  }
-}
-
 /**
  * Convert kebab-case to Title Case
  */
@@ -320,14 +301,20 @@ function generateLlmsTxt(
   // Add sections for each category
   // Sort categories to ensure components appear first
   const sortedCategories = Object.keys(groupedByCategory).sort((a, b) => {
-    if (a === 'components') return -1;
-    if (b === 'components') return 1;
+    if (a === 'components') {
+      return -1;
+    }
+    if (b === 'components') {
+      return 1;
+    }
     return a.localeCompare(b);
   });
 
   for (const category of sortedCategories) {
     const files = groupedByCategory[category];
-    if (files.length === 0) continue;
+    if (files.length === 0) {
+      continue;
+    }
 
     const sectionTitle = toTitleCase(category);
     content += `## ${sectionTitle}\n\n`;
@@ -337,7 +324,7 @@ function generateLlmsTxt(
 
     for (const file of files) {
       // Calculate relative path from the baseDir to the file
-      const relativePath = file.outputPath.startsWith(baseDir + '/')
+      const relativePath = file.outputPath.startsWith(`${baseDir}/`)
         ? `./${file.outputPath.substring(baseDir.length + 1)}`
         : `../${file.outputPath}`;
       content += `- [${file.title}](${relativePath})`;
@@ -373,23 +360,23 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
     throw new Error(`Failed to load project settings from ${argv.projectSettings}: ${error}`);
   }
 
-  console.log(`Building LLMs docs...`);
-  console.log(`Project settings: ${argv.projectSettings}`);
-  console.log(`Output directory: ${outputDir}`);
+  // Building LLMs docs...
+  // Project settings: ${argv.projectSettings}
+  // Output directory: ${outputDir}
   if (grep) {
-    console.log(`Filter pattern: ${grep}`);
+    // Filter pattern: ${grep}
   }
 
   // Find all components
   const components = await findComponentsToProcess(projectSettings, grep);
 
-  console.log(`Found ${components.length} components to process`);
+  // Found ${components.length} components to process
 
   // Find non-component markdown files if specified
   let nonComponentFiles: Array<{ markdownPath: string; outputPath: string }> = [];
   if (argv.nonComponentFolders && argv.nonComponentFolders.length > 0) {
     nonComponentFiles = findNonComponentMarkdownFiles(argv.nonComponentFolders, grep);
-    console.log(`Found ${nonComponentFiles.length} non-component markdown files to process`);
+    // Found ${nonComponentFiles.length} non-component markdown files to process
   }
 
   // Track generated files for llms.txt
@@ -408,8 +395,8 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       // Use the component's demo pathname to create the output structure
       // e.g., /material-ui/react-accordion/ -> material-ui/react-accordion.md
       const outputFileName = component.demos[0]
-        ? component.demos[0].demoPathname.replace(/^\//, '').replace(/\/$/, '') + '.md'
-        : component.componentInfo.apiPathname.replace(/^\//, '').replace(/\/$/, '') + '.md';
+        ? `${component.demos[0].demoPathname.replace(/^\//, '').replace(/\/$/, '')}.md`
+        : `${component.componentInfo.apiPathname.replace(/^\//, '').replace(/\/$/, '')}.md`;
 
       const outputPath = path.join(outputDir, outputFileName);
 
@@ -420,8 +407,8 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       }
 
       fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
-      console.log(`✓ Generated: ${outputFileName}`);
-      processedCount++;
+      // ✓ Generated: ${outputFileName}
+      processedCount += 1;
 
       // Track this file for llms.txt (avoid duplicates for components that share the same markdown file)
       if (component.markdownPath) {
@@ -445,9 +432,7 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
   // Process non-component markdown files
   for (const file of nonComponentFiles) {
     try {
-      console.log(
-        `Processing non-component file: ${path.relative(process.cwd(), file.markdownPath)}`,
-      );
+      // Processing non-component file: ${path.relative(process.cwd(), file.markdownPath)}
 
       // Process the markdown file with demo replacement
       const processedMarkdown = processMarkdownFile(file.markdownPath);
@@ -461,8 +446,8 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       }
 
       fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
-      console.log(`✓ Generated: ${file.outputPath}`);
-      processedCount++;
+      // ✓ Generated: ${file.outputPath}
+      processedCount += 1;
 
       // Track this file for llms.txt
       const { title, description } = extractMarkdownInfo(file.markdownPath);
@@ -498,12 +483,14 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
     }
 
     for (const [dirName, files] of Object.entries(groupedByFirstDir)) {
-      const projectName =
-        dirName === 'material-ui'
-          ? 'Material UI'
-          : dirName === 'system'
-            ? 'MUI System'
-            : dirName.charAt(0).toUpperCase() + dirName.slice(1);
+      let projectName;
+      if (dirName === 'material-ui') {
+        projectName = 'Material UI';
+      } else if (dirName === 'system') {
+        projectName = 'MUI System';
+      } else {
+        projectName = dirName.charAt(0).toUpperCase() + dirName.slice(1);
+      }
 
       const llmsContent = generateLlmsTxt(files, projectName, dirName);
       const llmsPath = path.join(outputDir, dirName, 'llms.txt');
@@ -515,11 +502,12 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       }
 
       fs.writeFileSync(llmsPath, llmsContent, 'utf-8');
-      console.log(`✓ Generated: ${dirName}/llms.txt`);
-      processedCount++;
+      // ✓ Generated: ${dirName}/llms.txt
+      processedCount += 1;
     }
   }
 
+  // eslint-disable-next-line no-console
   console.log(`\nCompleted! Generated ${processedCount} files in ${outputDir}`);
 }
 

From fbae974f1a63e40364b6ce19593fd3708bbcdaba Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 14:40:18 +0700
Subject: [PATCH 15/29] fix types

---
 packages-internal/scripts/generate-llms-txt/src/processApi.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index 21d092950fd3b2..c39b74f0919d70 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -75,7 +75,7 @@ function htmlToMarkdown(html: string): string {
     .replace(/<a\s+href="([^"]+)">([^<]+)<\/a>/gi, '[$2]($1)');
 
   // Handle lists - process them as complete units to avoid extra line breaks
-  markdown = markdown.replace(/<ul[^>]*>(.*?)<\/ul>/gis, (match, listContent) => {
+  markdown = markdown.replace(/<ul[^>]*>(.*?)<\/ul>/gis, (match, listContent: string) => {
     // Process each list item
     const items = listContent
       .split(/<\/li>/)

From 2e6281f27fb301aac2d68be8add3e8072abe3b2d Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 17:27:24 +0700
Subject: [PATCH 16/29] fix test

---
 .../getMaterialUiComponentInfo.test.ts        | 24 +++++++++++--------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts b/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts
index b065ccd0451b1d..bca773c1ccfdcf 100644
--- a/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts
+++ b/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts
@@ -30,16 +30,20 @@ describe('getMaterialUiComponentInfo', () => {
       // eslint-disable-next-line no-empty
     } catch (error) {}
     if (existed) {
-      expect(componentInfo.getDemos()).to.deep.equal([
-        {
-          demoPageTitle: 'Button Group',
-          demoPathname: '/material-ui/react-button-group/',
-        },
-        {
-          demoPageTitle: 'Button',
-          demoPathname: '/material-ui/react-button/',
-        },
-      ]);
+      const demos = componentInfo.getDemos();
+      expect(demos).to.have.lengthOf(2);
+      
+      expect(demos[0]).to.deep.include({
+        demoPageTitle: 'Button Group',
+        demoPathname: '/material-ui/react-button-group/',
+      });
+      expect(demos[0].filePath).to.include('button-group/button-group.md');
+      
+      expect(demos[1]).to.deep.include({
+        demoPageTitle: 'Button',
+        demoPathname: '/material-ui/react-button/',
+      });
+      expect(demos[1].filePath).to.include('buttons/buttons.md');
     }
   });
 });

From 0d42397597186d670c13ff45eee8efdf161b6bfc Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 18:11:43 +0700
Subject: [PATCH 17/29] concat components api into the main component

---
 scripts/buildLlmsDocs/index.ts | 59 +++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 16 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 56c8f9c370aa41..d8d4dea7dc2304 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -58,6 +58,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import yargs, { ArgumentsCamelCase } from 'yargs';
+import kebabCase from 'lodash/kebabCase';
 import { processMarkdownFile, processApiFile } from '@mui/internal-scripts/generate-llms-txt';
 import { ComponentInfo, ProjectSettings } from '@mui-internal/api-docs-builder';
 import { getHeaders } from '@mui/internal-markdown';
@@ -251,8 +252,33 @@ function processComponent(component: ComponentDocInfo): string | null {
   // Process the markdown file with demo replacement
   let processedMarkdown = processMarkdownFile(component.markdownPath);
 
-  // Add API section if JSON exists
-  if (component.apiJsonPath) {
+  // Read the frontmatter to get all components listed in this markdown file
+  const markdownContent = fs.readFileSync(component.markdownPath, 'utf-8');
+  const headers = getHeaders(markdownContent);
+  const componentsInPage = headers.components || [];
+
+  // Add API sections for all components listed in the frontmatter
+  if (componentsInPage.length > 0) {
+    for (const componentName of componentsInPage) {
+      // Construct the API JSON path based on the project settings
+      const apiJsonPath = path.join(
+        component.componentInfo.apiPagesDirectory,
+        `${kebabCase(componentName)}.json`,
+      );
+
+      if (fs.existsSync(apiJsonPath)) {
+        try {
+          const apiMarkdown = processApiFile(apiJsonPath);
+          processedMarkdown += `\n\n${apiMarkdown}`;
+        } catch (error) {
+          console.error(`Warning: Could not process API for ${componentName}:`, error);
+        }
+      } else {
+        console.warn(`Warning: API JSON file not found for ${componentName}: ${apiJsonPath}`);
+      }
+    }
+  } else if (component.apiJsonPath) {
+    // Fallback: Add API section for the primary component if no frontmatter components found
     try {
       const apiMarkdown = processApiFile(component.apiJsonPath);
       processedMarkdown += `\n\n${apiMarkdown}`;
@@ -267,8 +293,8 @@ function processComponent(component: ComponentDocInfo): string | null {
 /**
  * Convert kebab-case to Title Case
  */
-function toTitleCase(kebabCase: string): string {
-  return kebabCase
+function toTitleCase(kebabCaseStr: string): string {
+  return kebabCaseStr
     .split('-')
     .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
@@ -400,20 +426,21 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
 
       const outputPath = path.join(outputDir, outputFileName);
 
-      // Ensure the directory exists
-      const outputDirPath = path.dirname(outputPath);
-      if (!fs.existsSync(outputDirPath)) {
-        fs.mkdirSync(outputDirPath, { recursive: true });
-      }
+      // Check if this file has already been generated (avoid duplicates for components that share the same markdown file)
+      const existingFile = generatedFiles.find((f) => f.outputPath === outputFileName);
+      if (!existingFile) {
+        // Ensure the directory exists
+        const outputDirPath = path.dirname(outputPath);
+        if (!fs.existsSync(outputDirPath)) {
+          fs.mkdirSync(outputDirPath, { recursive: true });
+        }
 
-      fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
-      // ✓ Generated: ${outputFileName}
-      processedCount += 1;
+        fs.writeFileSync(outputPath, processedMarkdown, 'utf-8');
+        // ✓ Generated: ${outputFileName}
+        processedCount += 1;
 
-      // Track this file for llms.txt (avoid duplicates for components that share the same markdown file)
-      if (component.markdownPath) {
-        const existingFile = generatedFiles.find((f) => f.outputPath === outputFileName);
-        if (!existingFile) {
+        // Track this file for llms.txt
+        if (component.markdownPath) {
           const { title, description } = extractMarkdownInfo(component.markdownPath);
           generatedFiles.push({
             outputPath: outputFileName,

From 4d1c9161356bb9ed86088e973a130e73ee2c894e Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 18:29:06 +0700
Subject: [PATCH 18/29] fix first failed test

---
 packages-internal/scripts/generate-llms-txt/src/processApi.ts | 2 +-
 .../scripts/generate-llms-txt/test/processApi.test.ts         | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index c39b74f0919d70..8bca6c9818c759 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -143,7 +143,7 @@ function generatePropsTable(props: Record<string, ApiProp>): string {
   for (const [propName, prop] of propEntries) {
     const name = prop.deprecated ? `${propName} (deprecated)` : propName;
     const type = formatPropType(prop);
-    const defaultValue = prop.default || '-';
+    const defaultValue = prop.default ? `\`${prop.default}\`` : '-';
     const required = prop.required ? 'Yes' : 'No';
 
     let description = '';
diff --git a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
index d0720b02e51e5c..2c39d69ca03bb4 100644
--- a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
+++ b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
@@ -33,8 +33,8 @@ describe('processApi', () => {
       expect(result).to.include('## Import');
       expect(result).to.include("import Button from '@mui/material/Button';");
       expect(result).to.include('## Props');
-      expect(result).to.include("| color | string | `'primary'` | No |");
-      expect(result).to.include('| disabled | bool | `false` | No |');
+      expect(result).to.include("| color | `string` | `'primary'` | No |");
+      expect(result).to.include('| disabled | `bool` | `false` | No |');
     });
 
     it('should handle deprecated component', () => {

From 844eb25ece4362669a9314a16f5af9beb826c16f Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 23:09:48 +0700
Subject: [PATCH 19/29] fix type generation and update script

---
 package.json                                  |  2 +-
 .../generate-llms-txt/src/processApi.ts       | 25 ++++++++++++--
 .../generate-llms-txt/test/processApi.test.ts | 12 +++----
 scripts/buildLlmsDocs/index.ts                | 33 +++++++++++++++++--
 4 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/package.json b/package.json
index fc4a8930532a4a..bee8d6eb1c5d45 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "release:pack": "tsx scripts/releasePack.mts",
     "docs:api": "rimraf --glob ./docs/pages/**/api-docs ./docs/pages/**/api && pnpm docs:api:build",
     "docs:api:build": "tsx ./scripts/buidApiDocs/index.ts",
-    "docs:llms:build": "tsx ./scripts/buildLlmsDocs/index.ts --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts",
+    "docs:llms:build": "rimraf --glob ./docs/public/material-ui/ && tsx ./scripts/buildLlmsDocs/index.ts --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts --nonComponentFolders material/getting-started material/customization material/experimental-api material/guides material/integrations material/migration",
     "docs:build": "pnpm docs:llms:build && pnpm --filter docs build",
     "docs:build-sw": "pnpm --filter docs build-sw",
     "docs:build-color-preview": "babel-node scripts/buildColorTypes",
diff --git a/packages-internal/scripts/generate-llms-txt/src/processApi.ts b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
index 8bca6c9818c759..bd06d74566c876 100644
--- a/packages-internal/scripts/generate-llms-txt/src/processApi.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processApi.ts
@@ -56,6 +56,27 @@ interface ApiJson {
   deprecationInfo?: string;
 }
 
+/**
+ * Convert prop type description from HTML format
+ */
+function formatPropTypeDescription(html: string): string {
+  // Decode HTML entities
+  const result = html
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#124;/g, '|')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    // Replace <br> tags with space to maintain readability
+    .replace(/<br\s*\/?>/gi, ' ')
+    // Clean up excessive whitespace
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return result;
+}
+
 /**
  * Convert HTML to markdown
  */
@@ -112,8 +133,8 @@ function formatPropType(prop: ApiProp): string {
   let type = prop.type.name;
 
   if (prop.type.description) {
-    // Clean up the description
-    type = htmlToMarkdown(prop.type.description);
+    // Use specialized function for prop type descriptions
+    type = formatPropTypeDescription(prop.type.description);
   }
 
   if (prop.signature) {
diff --git a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
index 2c39d69ca03bb4..aac851e1a26f90 100644
--- a/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
+++ b/packages-internal/scripts/generate-llms-txt/test/processApi.test.ts
@@ -102,8 +102,8 @@ describe('processApi', () => {
       const result = processApiJson(apiJson);
 
       expect(result).to.include('`function(event: React.SyntheticEvent, value: number) => void`');
-      expect(result).to.include('{ root?: elementType, icon?: elementType }');
-      expect(result).to.include('Array<func | object> | func | object');
+      expect(result).to.include('`{ root?: elementType, icon?: elementType }`');
+      expect(result).to.include('`Array<func \\| object> \\| func \\| object`');
       expect(result).to.include('The system prop that allows defining system overrides');
     });
 
@@ -311,8 +311,8 @@ describe('processApi', () => {
 
       const result = processApiJson(apiJson);
 
-      expect(result).to.include('| children | node | - | Yes |');
-      expect(result).to.include('| optional | string | - | No |');
+      expect(result).to.include('| children | `node` | - | Yes |');
+      expect(result).to.include('| optional | `string` | - | No |');
     });
   });
 
@@ -345,7 +345,7 @@ describe('processApi', () => {
       const result = processApiFile(filePath);
 
       expect(result).to.include('# TestComponent API');
-      expect(result).to.include('| test | bool | `true` | No |');
+      expect(result).to.include('| test | `bool` | `true` | No |');
     });
   });
 
@@ -367,7 +367,7 @@ describe('processApi', () => {
 
       const result = processApiJson(apiJson);
 
-      expect(result).to.include('Array<func | object> | func');
+      expect(result).to.include('`Array<func \\| object> \\| func`');
       expect(result).to.include('Test paragraph');
       expect(result).to.include('- Item 1');
       expect(result).to.include('- Item 2');
diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index d8d4dea7dc2304..f6b9e8c3da3fa7 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -81,6 +81,7 @@ interface GeneratedFile {
   description: string;
   originalMarkdownPath: string;
   category: string;
+  orderIndex?: number; // Track the order for non-component folders
 }
 
 type CommandOptions = {
@@ -325,7 +326,7 @@ function generateLlmsTxt(
   content += `It contains comprehensive guides, components, and utilities for building user interfaces.\n\n`;
 
   // Add sections for each category
-  // Sort categories to ensure components appear first
+  // Sort categories to ensure components appear first, then by orderIndex for non-component folders
   const sortedCategories = Object.keys(groupedByCategory).sort((a, b) => {
     if (a === 'components') {
       return -1;
@@ -333,6 +334,17 @@ function generateLlmsTxt(
     if (b === 'components') {
       return 1;
     }
+
+    // For non-component categories, check if they have orderIndex
+    const filesA = groupedByCategory[a];
+    const filesB = groupedByCategory[b];
+    const orderIndexA = filesA[0]?.orderIndex ?? Number.MAX_SAFE_INTEGER;
+    const orderIndexB = filesB[0]?.orderIndex ?? Number.MAX_SAFE_INTEGER;
+
+    if (orderIndexA !== orderIndexB) {
+      return orderIndexA - orderIndexB;
+    }
+
     return a.localeCompare(b);
   });
 
@@ -345,8 +357,11 @@ function generateLlmsTxt(
     const sectionTitle = toTitleCase(category);
     content += `## ${sectionTitle}\n\n`;
 
-    // Sort files by title
-    files.sort((a, b) => a.title.localeCompare(b.title));
+    // Sort files by title (components) or maintain original order (non-components)
+    if (category === 'components') {
+      files.sort((a, b) => a.title.localeCompare(b.title));
+    }
+    // Non-component files are already in the order they were discovered
 
     for (const file of files) {
       // Calculate relative path from the baseDir to the file
@@ -485,12 +500,24 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
       const pathParts = file.outputPath.split('/');
       const category = pathParts.reverse()[1];
 
+      // Find the order index based on which folder this file belongs to
+      let orderIndex = -1;
+      if (argv.nonComponentFolders) {
+        for (let i = 0; i < argv.nonComponentFolders.length; i += 1) {
+          if (file.markdownPath.includes(`/${argv.nonComponentFolders[i]}/`)) {
+            orderIndex = i;
+            break;
+          }
+        }
+      }
+
       generatedFiles.push({
         outputPath: file.outputPath,
         title,
         description,
         originalMarkdownPath: file.markdownPath,
         category,
+        orderIndex,
       });
     } catch (error) {
       console.error(`✗ Error processing ${file.markdownPath}:`, error);

From f944892dfee60e12a550e961993251259e997dee Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 10 Jun 2025 23:42:32 +0700
Subject: [PATCH 20/29] run prettier

---
 .../materialUi/getMaterialUiComponentInfo.test.ts             | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts b/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts
index bca773c1ccfdcf..c9247f6a58eca5 100644
--- a/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts
+++ b/packages/api-docs-builder-core/materialUi/getMaterialUiComponentInfo.test.ts
@@ -32,13 +32,13 @@ describe('getMaterialUiComponentInfo', () => {
     if (existed) {
       const demos = componentInfo.getDemos();
       expect(demos).to.have.lengthOf(2);
-      
+
       expect(demos[0]).to.deep.include({
         demoPageTitle: 'Button Group',
         demoPathname: '/material-ui/react-button-group/',
       });
       expect(demos[0].filePath).to.include('button-group/button-group.md');
-      
+
       expect(demos[1]).to.deep.include({
         demoPageTitle: 'Button',
         demoPathname: '/material-ui/react-button/',

From 338c2a3d5c476982c5ce0e28a2a09de2f89cb673 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Wed, 11 Jun 2025 09:01:33 +0700
Subject: [PATCH 21/29] only warn on dev

---
 .../scripts/generate-llms-txt/src/processComponent.ts         | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
index 51480be06d4ff9..38275b32675d3c 100755
--- a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
@@ -60,7 +60,9 @@ export function replaceDemoWithSnippet(
 
       // If no files found, return original match
       if (!codeSnippet) {
-        console.warn(`Demo file not found: ${filename}`);
+        if (process.env.NODE_ENV !== 'test') {
+          console.warn(`Demo file not found: ${filename}`);
+        }
         return match;
       }
 

From e52801475b1a0ed786875175357fa182bdbd3178 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Fri, 13 Jun 2025 14:53:28 +0700
Subject: [PATCH 22/29] fix(buildLlmsDocs): exclude headers from being captured
 as descriptions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The extractMarkdownInfo function was incorrectly capturing "## Usage" as the description
for template README files. Updated the regex to use negative lookahead to exclude headers
and added an additional check to ensure captured text doesn't start with '#'.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/buildLlmsDocs/index.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index f6b9e8c3da3fa7..cf2d66aa5d90bd 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -181,9 +181,9 @@ function extractMarkdownInfo(markdownPath: string): { title: string; description
     if (descriptionMatch) {
       description = descriptionMatch[1].trim();
     } else {
-      // Fallback: get first paragraph after title
-      const paragraphMatch = content.match(/^# .+\n\n(.+?)(?:\n\n|$)/m);
-      if (paragraphMatch) {
+      // Fallback: get first paragraph after title (excluding headers)
+      const paragraphMatch = content.match(/^# .+\n\n(?!#)(.+?)(?:\n\n|$)/m);
+      if (paragraphMatch && !paragraphMatch[1].startsWith('#')) {
         description = paragraphMatch[1].trim();
       }
     }

From 7abb41c3f3ad548f23780937184a465001d92ed2 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Fri, 13 Jun 2025 15:39:25 +0700
Subject: [PATCH 23/29] cleanup markdown

---
 .../generate-llms-txt/src/processComponent.ts | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
index 38275b32675d3c..beede3bec292f5 100755
--- a/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
+++ b/packages-internal/scripts/generate-llms-txt/src/processComponent.ts
@@ -6,6 +6,27 @@ interface DemoReplaceOptions {
   includeTypeScript?: boolean;
 }
 
+/**
+ * Removes {{"component": ...}} syntax from markdown content
+ * @param markdownContent - The markdown content to clean
+ * @returns The cleaned markdown content
+ */
+export function removeComponentSyntax(markdownContent: string): string {
+  // Regular expression to match {{"component": "ComponentName"}} pattern
+  const componentRegex = /\{\{"component":\s*"[^"]+"\}\}/g;
+  return markdownContent.replace(componentRegex, '');
+}
+
+/**
+ * Converts <p class="description"> HTML tags to plain text in markdown
+ * @param markdownContent - The markdown content to clean
+ * @returns The cleaned markdown content
+ */
+export function cleanDescriptionTags(markdownContent: string): string {
+  // Replace <p class="description">...</p> with just the content
+  return markdownContent.replace(/<p class="description">([^<]+)<\/p>/g, '$1');
+}
+
 /**
  * Parses markdown content and replaces demo syntax with code snippets
  * @param markdownContent - The markdown content to parse
@@ -81,7 +102,7 @@ export function replaceDemoWithSnippet(
  * @returns The processed markdown content
  */
 export function processMarkdownFile(filePath: string, options: DemoReplaceOptions = {}): string {
-  const content = fs.readFileSync(filePath, 'utf-8');
+  let content = fs.readFileSync(filePath, 'utf-8');
   const dir = path.dirname(filePath);
 
   // Set basePath relative to markdown file location if not provided
@@ -90,5 +111,12 @@ export function processMarkdownFile(filePath: string, options: DemoReplaceOption
     basePath: options.basePath || dir,
   };
 
+  // First, remove component syntax
+  content = removeComponentSyntax(content);
+
+  // Clean description HTML tags
+  content = cleanDescriptionTags(content);
+
+  // Then, replace demo syntax with code snippets
   return replaceDemoWithSnippet(content, filePath, processOptions);
 }

From 112751c630cf26159b46f114c2d46207074cd9bd Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 16 Jun 2025 09:00:05 +0700
Subject: [PATCH 24/29] feat(buildLlmsDocs): add configurable domain for
 absolute URLs in llms.txt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add --domain CLI option with default value 'mui.com'
- Update generateLlmsTxt to use absolute URLs instead of relative paths
- Remove unused baseDir parameter from generateLlmsTxt function

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/buildLlmsDocs/index.ts | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index cf2d66aa5d90bd..2a3f12821e762c 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -89,6 +89,7 @@ type CommandOptions = {
   outputDir?: string;
   projectSettings?: string;
   nonComponentFolders?: string[];
+  domain?: string;
 };
 
 /**
@@ -307,7 +308,7 @@ function toTitleCase(kebabCaseStr: string): string {
 function generateLlmsTxt(
   generatedFiles: GeneratedFile[],
   projectName: string,
-  baseDir: string,
+  domain: string,
 ): string {
   // Group files by category
   const groupedByCategory: Record<string, GeneratedFile[]> = {};
@@ -364,11 +365,10 @@ function generateLlmsTxt(
     // Non-component files are already in the order they were discovered
 
     for (const file of files) {
-      // Calculate relative path from the baseDir to the file
-      const relativePath = file.outputPath.startsWith(`${baseDir}/`)
-        ? `./${file.outputPath.substring(baseDir.length + 1)}`
-        : `../${file.outputPath}`;
-      content += `- [${file.title}](${relativePath})`;
+      // Generate absolute URL with domain
+      const urlPath = file.outputPath.replace(/\.md$/, '/');
+      const absoluteUrl = `https://${domain}/${urlPath}`;
+      content += `- [${file.title}](${absoluteUrl})`;
       if (file.description) {
         content += `: ${file.description}`;
       }
@@ -386,6 +386,7 @@ function generateLlmsTxt(
 async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
   const grep = argv.grep ? new RegExp(argv.grep) : null;
   const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
+  const domain = argv.domain || 'mui.com';
 
   // Load project settings from the specified path
   if (!argv.projectSettings) {
@@ -546,7 +547,7 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
         projectName = dirName.charAt(0).toUpperCase() + dirName.slice(1);
       }
 
-      const llmsContent = generateLlmsTxt(files, projectName, dirName);
+      const llmsContent = generateLlmsTxt(files, projectName, domain);
       const llmsPath = path.join(outputDir, dirName, 'llms.txt');
 
       // Ensure directory exists
@@ -594,6 +595,11 @@ yargs(process.argv.slice(2))
           description: 'List of folders from docs/data/ to process non-component markdown files.',
           type: 'array',
           default: [],
+        })
+        .option('domain', {
+          description: 'Domain to use for absolute URLs in llms.txt files.',
+          type: 'string',
+          default: 'mui.com',
         });
     },
     handler: buildLlmsDocs,

From bbdc9d5226f163f3cd40142579122a62f96a841c Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 16 Jun 2025 15:32:35 +0700
Subject: [PATCH 25/29] refactor(buildLlmsDocs): move nonComponentFolders
 config from CLI to projectSettings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the nonComponentFolders configuration from command-line argument to projectSettings
for better maintainability and consistency with other project configurations.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 package.json                                  |  2 +-
 .../materialUi/projectSettings.ts             |  8 ++++
 packages/api-docs-builder/ProjectSettings.ts  |  5 +++
 scripts/buildLlmsDocs/index.ts                | 40 +++++++------------
 4 files changed, 29 insertions(+), 26 deletions(-)

diff --git a/package.json b/package.json
index ce4f47e17016ab..1aa4bd082d2ffc 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "release:pack": "tsx scripts/releasePack.mts",
     "docs:api": "rimraf --glob ./docs/pages/**/api-docs ./docs/pages/**/api && pnpm docs:api:build",
     "docs:api:build": "tsx ./scripts/buidApiDocs/index.ts",
-    "docs:llms:build": "rimraf --glob ./docs/public/material-ui/ && tsx ./scripts/buildLlmsDocs/index.ts --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts --nonComponentFolders material/getting-started material/customization material/experimental-api material/guides material/integrations material/migration",
+    "docs:llms:build": "rimraf --glob ./docs/public/material-ui/ && tsx ./scripts/buildLlmsDocs/index.ts --projectSettings ./packages/api-docs-builder-core/materialUi/projectSettings.ts",
     "docs:build": "pnpm docs:llms:build && pnpm --filter docs build",
     "docs:build-sw": "pnpm --filter docs build-sw",
     "docs:build-color-preview": "babel-node scripts/buildColorTypes",
diff --git a/packages/api-docs-builder-core/materialUi/projectSettings.ts b/packages/api-docs-builder-core/materialUi/projectSettings.ts
index b443e8664e983e..c8391266a79c36 100644
--- a/packages/api-docs-builder-core/materialUi/projectSettings.ts
+++ b/packages/api-docs-builder-core/materialUi/projectSettings.ts
@@ -46,4 +46,12 @@ export const projectSettings: ProjectSettings = {
   isGlobalClassName: isGlobalState,
   // #host-reference
   baseApiUrl: 'https://mui.com',
+  nonComponentFolders: [
+    'material/getting-started',
+    'material/customization',
+    'material/experimental-api',
+    'material/guides',
+    'material/integrations',
+    'material/migration',
+  ],
 };
diff --git a/packages/api-docs-builder/ProjectSettings.ts b/packages/api-docs-builder/ProjectSettings.ts
index e814a25d7ee428..c5b752bd153cae 100644
--- a/packages/api-docs-builder/ProjectSettings.ts
+++ b/packages/api-docs-builder/ProjectSettings.ts
@@ -113,4 +113,9 @@ export interface ProjectSettings {
    * Determines the base API URL for generated JSDocs
    */
   baseApiUrl?: string;
+  /**
+   * Determines the non-component folders to be included in the llms.txt file.
+   * The folders are relative to the `docs/data` directory.
+   */
+  nonComponentFolders?: string[];
 }
diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 2a3f12821e762c..a592dc45f4339e 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -88,8 +88,6 @@ type CommandOptions = {
   grep?: string;
   outputDir?: string;
   projectSettings?: string;
-  nonComponentFolders?: string[];
-  domain?: string;
 };
 
 /**
@@ -308,7 +306,7 @@ function toTitleCase(kebabCaseStr: string): string {
 function generateLlmsTxt(
   generatedFiles: GeneratedFile[],
   projectName: string,
-  domain: string,
+  baseDir: string,
 ): string {
   // Group files by category
   const groupedByCategory: Record<string, GeneratedFile[]> = {};
@@ -365,10 +363,11 @@ function generateLlmsTxt(
     // Non-component files are already in the order they were discovered
 
     for (const file of files) {
-      // Generate absolute URL with domain
-      const urlPath = file.outputPath.replace(/\.md$/, '/');
-      const absoluteUrl = `https://${domain}/${urlPath}`;
-      content += `- [${file.title}](${absoluteUrl})`;
+      // Calculate relative path from the baseDir to the file
+      const relativePath = file.outputPath.startsWith(`${baseDir}/`)
+        ? `./${file.outputPath.substring(baseDir.length + 1)}`
+        : `../${file.outputPath}`;
+      content += `- [${file.title}](${relativePath})`;
       if (file.description) {
         content += `: ${file.description}`;
       }
@@ -386,7 +385,6 @@ function generateLlmsTxt(
 async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
   const grep = argv.grep ? new RegExp(argv.grep) : null;
   const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
-  const domain = argv.domain || 'mui.com';
 
   // Load project settings from the specified path
   if (!argv.projectSettings) {
@@ -414,10 +412,11 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
 
   // Found ${components.length} components to process
 
-  // Find non-component markdown files if specified
+  // Find non-component markdown files if specified in project settings
   let nonComponentFiles: Array<{ markdownPath: string; outputPath: string }> = [];
-  if (argv.nonComponentFolders && argv.nonComponentFolders.length > 0) {
-    nonComponentFiles = findNonComponentMarkdownFiles(argv.nonComponentFolders, grep);
+  const nonComponentFolders = (projectSettings as any).nonComponentFolders;
+  if (nonComponentFolders && nonComponentFolders.length > 0) {
+    nonComponentFiles = findNonComponentMarkdownFiles(nonComponentFolders, grep);
     // Found ${nonComponentFiles.length} non-component markdown files to process
   }
 
@@ -503,9 +502,9 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
 
       // Find the order index based on which folder this file belongs to
       let orderIndex = -1;
-      if (argv.nonComponentFolders) {
-        for (let i = 0; i < argv.nonComponentFolders.length; i += 1) {
-          if (file.markdownPath.includes(`/${argv.nonComponentFolders[i]}/`)) {
+      if (nonComponentFolders) {
+        for (let i = 0; i < nonComponentFolders.length; i += 1) {
+          if (file.markdownPath.includes(`/${nonComponentFolders[i]}/`)) {
             orderIndex = i;
             break;
           }
@@ -547,7 +546,7 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
         projectName = dirName.charAt(0).toUpperCase() + dirName.slice(1);
       }
 
-      const llmsContent = generateLlmsTxt(files, projectName, domain);
+      const llmsContent = generateLlmsTxt(files, projectName, dirName);
       const llmsPath = path.join(outputDir, dirName, 'llms.txt');
 
       // Ensure directory exists
@@ -591,16 +590,7 @@ yargs(process.argv.slice(2))
           type: 'string',
           demandOption: true,
         })
-        .option('nonComponentFolders', {
-          description: 'List of folders from docs/data/ to process non-component markdown files.',
-          type: 'array',
-          default: [],
-        })
-        .option('domain', {
-          description: 'Domain to use for absolute URLs in llms.txt files.',
-          type: 'string',
-          default: 'mui.com',
-        });
+;
     },
     handler: buildLlmsDocs,
   })

From 9523d2d06a7fb6efae3328468915fc04af8f20b6 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 16 Jun 2025 15:50:19 +0700
Subject: [PATCH 26/29] revert: restore domain CLI feature for llms.txt
 generation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restore the --domain CLI option that was removed in the previous commit.
This allows configuring the domain for absolute URLs in llms.txt files.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/buildLlmsDocs/index.ts | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index a592dc45f4339e..691b49d2fb6bc2 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -88,6 +88,7 @@ type CommandOptions = {
   grep?: string;
   outputDir?: string;
   projectSettings?: string;
+  domain?: string;
 };
 
 /**
@@ -306,7 +307,7 @@ function toTitleCase(kebabCaseStr: string): string {
 function generateLlmsTxt(
   generatedFiles: GeneratedFile[],
   projectName: string,
-  baseDir: string,
+  domain: string,
 ): string {
   // Group files by category
   const groupedByCategory: Record<string, GeneratedFile[]> = {};
@@ -363,11 +364,10 @@ function generateLlmsTxt(
     // Non-component files are already in the order they were discovered
 
     for (const file of files) {
-      // Calculate relative path from the baseDir to the file
-      const relativePath = file.outputPath.startsWith(`${baseDir}/`)
-        ? `./${file.outputPath.substring(baseDir.length + 1)}`
-        : `../${file.outputPath}`;
-      content += `- [${file.title}](${relativePath})`;
+      // Generate absolute URL with domain
+      const urlPath = file.outputPath.replace(/\.md$/, '/');
+      const absoluteUrl = `https://${domain}/${urlPath}`;
+      content += `- [${file.title}](${absoluteUrl})`;
       if (file.description) {
         content += `: ${file.description}`;
       }
@@ -385,6 +385,7 @@ function generateLlmsTxt(
 async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
   const grep = argv.grep ? new RegExp(argv.grep) : null;
   const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
+  const domain = argv.domain || 'mui.com';
 
   // Load project settings from the specified path
   if (!argv.projectSettings) {
@@ -546,7 +547,7 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
         projectName = dirName.charAt(0).toUpperCase() + dirName.slice(1);
       }
 
-      const llmsContent = generateLlmsTxt(files, projectName, dirName);
+      const llmsContent = generateLlmsTxt(files, projectName, domain);
       const llmsPath = path.join(outputDir, dirName, 'llms.txt');
 
       // Ensure directory exists
@@ -590,7 +591,11 @@ yargs(process.argv.slice(2))
           type: 'string',
           demandOption: true,
         })
-;
+        .option('domain', {
+          description: 'Domain to use for absolute URLs in llms.txt files.',
+          type: 'string',
+          default: 'mui.com',
+        });
     },
     handler: buildLlmsDocs,
   })

From 41c972846336bf69f0ea81810b1978b32884931c Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 17 Jun 2025 12:33:20 +0700
Subject: [PATCH 27/29] Revert "revert: restore domain CLI feature for llms.txt
 generation"

This reverts commit 9523d2d06a7fb6efae3328468915fc04af8f20b6.
---
 scripts/buildLlmsDocs/index.ts | 21 ++++++++-------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 691b49d2fb6bc2..a592dc45f4339e 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -88,7 +88,6 @@ type CommandOptions = {
   grep?: string;
   outputDir?: string;
   projectSettings?: string;
-  domain?: string;
 };
 
 /**
@@ -307,7 +306,7 @@ function toTitleCase(kebabCaseStr: string): string {
 function generateLlmsTxt(
   generatedFiles: GeneratedFile[],
   projectName: string,
-  domain: string,
+  baseDir: string,
 ): string {
   // Group files by category
   const groupedByCategory: Record<string, GeneratedFile[]> = {};
@@ -364,10 +363,11 @@ function generateLlmsTxt(
     // Non-component files are already in the order they were discovered
 
     for (const file of files) {
-      // Generate absolute URL with domain
-      const urlPath = file.outputPath.replace(/\.md$/, '/');
-      const absoluteUrl = `https://${domain}/${urlPath}`;
-      content += `- [${file.title}](${absoluteUrl})`;
+      // Calculate relative path from the baseDir to the file
+      const relativePath = file.outputPath.startsWith(`${baseDir}/`)
+        ? `./${file.outputPath.substring(baseDir.length + 1)}`
+        : `../${file.outputPath}`;
+      content += `- [${file.title}](${relativePath})`;
       if (file.description) {
         content += `: ${file.description}`;
       }
@@ -385,7 +385,6 @@ function generateLlmsTxt(
 async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<void> {
   const grep = argv.grep ? new RegExp(argv.grep) : null;
   const outputDir = argv.outputDir || path.join(process.cwd(), 'docs/public');
-  const domain = argv.domain || 'mui.com';
 
   // Load project settings from the specified path
   if (!argv.projectSettings) {
@@ -547,7 +546,7 @@ async function buildLlmsDocs(argv: ArgumentsCamelCase<CommandOptions>): Promise<
         projectName = dirName.charAt(0).toUpperCase() + dirName.slice(1);
       }
 
-      const llmsContent = generateLlmsTxt(files, projectName, domain);
+      const llmsContent = generateLlmsTxt(files, projectName, dirName);
       const llmsPath = path.join(outputDir, dirName, 'llms.txt');
 
       // Ensure directory exists
@@ -591,11 +590,7 @@ yargs(process.argv.slice(2))
           type: 'string',
           demandOption: true,
         })
-        .option('domain', {
-          description: 'Domain to use for absolute URLs in llms.txt files.',
-          type: 'string',
-          default: 'mui.com',
-        });
+;
     },
     handler: buildLlmsDocs,
   })

From 929cfd649e423a44c22816be22dd42b048145596 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 17 Jun 2025 12:34:20 +0700
Subject: [PATCH 28/29] remove dot prefix

---
 scripts/buildLlmsDocs/index.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index a592dc45f4339e..037817354492eb 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -365,7 +365,7 @@ function generateLlmsTxt(
     for (const file of files) {
       // Calculate relative path from the baseDir to the file
       const relativePath = file.outputPath.startsWith(`${baseDir}/`)
-        ? `./${file.outputPath.substring(baseDir.length + 1)}`
+        ? `/${file.outputPath.substring(baseDir.length + 1)}`
         : `../${file.outputPath}`;
       content += `- [${file.title}](${relativePath})`;
       if (file.description) {
@@ -589,8 +589,7 @@ yargs(process.argv.slice(2))
             'Path to the project settings module that exports ProjectSettings interface.',
           type: 'string',
           demandOption: true,
-        })
-;
+        });
     },
     handler: buildLlmsDocs,
   })

From 7c9e60ede9b854483762146225422ccd871e6ecf Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Tue, 17 Jun 2025 22:26:33 +0700
Subject: [PATCH 29/29] add baseDir to relative links

---
 scripts/buildLlmsDocs/index.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/buildLlmsDocs/index.ts b/scripts/buildLlmsDocs/index.ts
index 037817354492eb..59b8bbe36d0acd 100644
--- a/scripts/buildLlmsDocs/index.ts
+++ b/scripts/buildLlmsDocs/index.ts
@@ -365,8 +365,8 @@ function generateLlmsTxt(
     for (const file of files) {
       // Calculate relative path from the baseDir to the file
       const relativePath = file.outputPath.startsWith(`${baseDir}/`)
-        ? `/${file.outputPath.substring(baseDir.length + 1)}`
-        : `../${file.outputPath}`;
+        ? `/${baseDir}/${file.outputPath.substring(baseDir.length + 1)}`
+        : `/${file.outputPath}`;
       content += `- [${file.title}](${relativePath})`;
       if (file.description) {
         content += `: ${file.description}`;