build: generate llms.txt and markdown files of the documentation for optimal AI consumption

ToMESSKa · ToMESSKa · commit e1632c5c9d30 · 2025-09-25T14:38:30.000+02:00
INSTUI-4701
diff --git a/docs/contributor-docs/ai-features.md b/docs/contributor-docs/ai-features.md
@@ -0,0 +1,77 @@
+---
+title: AI features
+category: Contributor Guides
+order: 8
+---
+
+## Generating AI agent friendly markdown files for components and guides
+
+InstUI's JSON metadata is used to create a markdown version of the documentation for easier use by AI tools and coding assistants.
+
+These markdown files are created during the build process then are made available for users using specific links.
+
+This collection includes structured files for almost everything under the 'Getting Started', 'Guides', 'Patterns' and 'Components' (including Components/AI Components and Components/Utilities) sections of the documentation.
+
+How it works:
+The core logic resides in `packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-markdowns.mts`.
+
+1. **Input and output**  
+   Input: The script processes the JSON files found under `packages/__docs__/__build__/docs` if they belong to the corresponding sections mentioned above.  
+   Output: A directory of generated .md files under `packages/__docs__/__build__/markdowns`, which are also compressed into a documentation.zip archive as well which also can be found in this directory.
+
+2. **Data loading and classification**  
+   The script reads all JSON files from the specified docs folder.
+   Identifies the necessary components and guides based on data.category value.
+
+3. **Markdown generation**  
+   A markdown file is generated using the data found under the 'description' key. As for components, an addtional table of props and a 'Usage' section is generated for showing how to import the component.
+   As for the table of props, the props of a child component (e.g. Tabs.Panel) of a parent component (e.g. Tabs) is also included in the table.
+
+4. **Index file creation and packaging**  
+   After all individual markdown files are written, index.md file is generated, which acts as a master list of contents for the entire documentation set.
+   Finally, the script uses the system's zip command to package all .md files in the output directory into the final documentation.zip file, which can be downloaded here: https://instructure.design/markdowns/documentation.zip  
+   The AI-friendly markdown files are now avaliable either downloading the documentation.zip file or through a link that follows this pattern: https://instructure.design/markdowns/Alert.md
+
+## Generating llms.txt for LLMs
+
+In addition to the markdown files, a llms.txt file is also generated. This file is specifically formatted for optimal consumption by Large Language Models (LLMs) and AI coding agents.
+This file contains a catalog of links pointing to the online markdown files of InstUI components and guides generated above and short description of each component/guide
+
+How it works:
+The core logic resides in `packages/__docs__/buildScripts/ai-accessible-documentation/ggenerate-ai-accessible-llms-file.mts`.
+
+1. **Input and output**  
+   Input: The script processes the following JSON file: `packages/__docs__/__build__/markdown-and-sources-data.json`  
+   Output: An llms.txt file is placed into `packages/__docs__/__build__` which can be found here: https://instructure.design/llms.txt
+
+2. **Data loading and classification**  
+   The script indenftifies the necessary elements looking for "Getting Started", "Guides", "Patterns", and "Components" section names.
+
+3. **Markdown generation**  
+   It creates a documentation structure like this:
+
+   ```md
+   ---
+   type: code
+   ---
+
+   # Instructure UI (InstUI) - React Component Library
+
+   ## Documentation
+
+   ### User Guides
+
+   #### Getting Started
+
+   #### Guides
+
+   #### Patterns
+
+   ### Components
+
+   #### Utilities
+
+   #### AI components
+   ```
+
+   It generates links for the components/guides and appends a brief summary of each of them using the `packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json` file, searching for matching component/guide title.
diff --git a/docs/contributor-docs/contributing.md b/docs/contributor-docs/contributing.md
@@ -102,6 +102,7 @@ Please update the documentation and examples with any changes.
 11. Visit [http://localhost:9090](http://localhost:9090) in a browser. You should see your component listed in the docs.
 12. Start making changes to your component, and watch it update in the browser automatically.
 13. Resolve all `FIXME` comments in the generated code (except in the `MyComponentLocator.ts`).
+14. Add a short description of the new component to the `packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json` file. This will optimize the component's documentation for consumption by AI agents.
 
 ### Adding a new dependency
 
diff --git a/docs/getting-started/accessibility.md b/docs/getting-started/accessibility.md
@@ -2,6 +2,7 @@
 title: Accessibility
 category: Getting Started
 order: 6
+relevantForAI: true
 ---
 
 ## Accessibility
diff --git a/docs/getting-started/theming-components.md b/docs/getting-started/theming-components.md
@@ -2,6 +2,7 @@
 title: Themes
 category: Getting Started
 order: 8
+relevantForAI: true
 ---
 
 ## Themes
diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md
@@ -2,6 +2,7 @@
 title: Usage
 category: Getting Started
 order: 1
+relevantForAI: true
 ---
 
 ## Quick Start
@@ -74,6 +75,20 @@ Congrats, you have now a (very) basic app that uses Instructure UI :)
 
 Just add the `@instructure/ui` dependency as shown above and wrap the part of your app that will use InstUI in `<InstUISettingsProvider>` and start using InstUI components.
 
+## Using InstUI with AI coding agents
+
+InstUI provides a compressed, downloadable collection of all component documentation and user guides in an AI-agent-friendly markdown format.
+
+You can download the archive from the following link:
+https://instructure.design/markdowns/documentation.zip
+
+The download includes an index.md file that references all available documentation within the compressed folder.
+
+These files are designed to be used as context for AI coding agents.
+
+Additionally, an llms.txt file is available. This file contains a catalog of links pointing to the online markdown files for InstUI components and guides, which are also accessible to AI agents. It can be found at:
+https://instructure.design/llms.txt
+
 ## Further reading
 
 - To use a different theme or customize one read about [Using theme overrides](#using-theme-overrides)
diff --git a/docs/guides/accessing-the-dom.md b/docs/guides/accessing-the-dom.md
@@ -2,6 +2,7 @@
 title: Accessing the DOM
 category: Guides
 order: 5
+relevantForAI: true
 ---
 
 ## Accessing the DOM
diff --git a/docs/guides/color-system.md b/docs/guides/color-system.md
@@ -2,6 +2,7 @@
 title: Color System
 category: Guides
 order: 6
+relevantForAI: true
 ---
 
 ## Colors
diff --git a/docs/guides/focus-management.md b/docs/guides/focus-management.md
@@ -2,6 +2,7 @@
 title: Focus Management
 category: Guides
 order: 4
+relevantForAI: true
 ---
 
 ## The Focus Management Problem
diff --git a/docs/guides/form-errors.md b/docs/guides/form-errors.md
@@ -2,6 +2,7 @@
 title: Form Errors
 category: Guides
 order: 7
+relevantForAI: true
 ---
 
 # Adding Error Messages to Form Components
diff --git a/docs/guides/layout-spacing.md b/docs/guides/layout-spacing.md
@@ -2,6 +2,7 @@
 title: Layout Spacing
 category: Guides
 order: 8
+relevantForAI: true
 ---
 
 # Layout Spacing
diff --git a/docs/guides/module-federation.md b/docs/guides/module-federation.md
@@ -2,6 +2,7 @@
 title: Module federation
 category: Guides
 order: 1
+relevantForAI: true
 ---
 
 # Module federation
diff --git a/docs/guides/server-side-rendering.md b/docs/guides/server-side-rendering.md
@@ -2,6 +2,7 @@
 title: Server side rendering (SSR)
 category: Guides
 order: 2
+relevantForAI: true
 ---
 
 # SSR with Next.js
diff --git a/docs/guides/typography-system.md b/docs/guides/typography-system.md
@@ -2,6 +2,7 @@
 title: Typography
 category: Guides
 order: 9
+relevantForAI: true
 ---
 
 # Typography
diff --git a/docs/guides/using-theme-overrides.md b/docs/guides/using-theme-overrides.md
@@ -2,6 +2,7 @@
 title: Using theme overrides
 category: Guides
 order: 3
+relevantForAI: true
 ---
 
 ## Using theme overrides
diff --git a/docs/patterns/ContentAlignment.md b/docs/patterns/ContentAlignment.md
@@ -2,6 +2,7 @@
 title: Content Alignment
 category: Patterns
 id: ContentAlignment
+relevantForAI: true
 ---
 
 ## Content Alignment
diff --git a/docs/patterns/DestroyAction.md b/docs/patterns/DestroyAction.md
@@ -2,6 +2,7 @@
 title: Destroy Action
 category: Patterns
 id: DestroyAction
+relevantForAI: true
 ---
 
 ## Destroy Action
diff --git a/docs/patterns/Search.md b/docs/patterns/Search.md
@@ -2,6 +2,7 @@
 title: Search
 category: Patterns
 id: Search
+relevantForAI: true
 ---
 
 ## Search
diff --git a/docs/patterns/UsingIcons.md b/docs/patterns/UsingIcons.md
@@ -2,6 +2,7 @@
 title: Using Icons
 category: Patterns
 id: UsingIcons
+relevantForAI: true
 ---
 
 ## Using Icons
diff --git a/packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-llms-file.mts b/packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-llms-file.mts
@@ -0,0 +1,164 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Processes InstUI JSON metadata to generate a file
+ * formatted for Large Language Models (LLMs) and AI agent consumption
+ * - Contains a catalog of links pointing to ai-accessible markdown files about InstUI components and guides
+ * - Contains a summary of each component/guide next to the links
+*/
+
+import { writeFileSync, readFileSync } from 'fs'
+
+interface SectionData {
+  docs?: string[]
+  sections?: string[]
+  title?: string
+}
+
+interface GenerateLLMSOptions {
+  summariesFilePath?: string
+  baseUrl?: string
+  outputFilePath?: string
+}
+
+function generateAIAccessibleLlmsFile(
+  sourceFilePath: string,
+  options: GenerateLLMSOptions = {}
+): string {
+  const { summariesFilePath, baseUrl = '', outputFilePath } = options
+
+  const fileContent = readFileSync(sourceFilePath, 'utf-8')
+  const jsonData = JSON.parse(fileContent)
+  const { sections, library } = jsonData
+
+  const version = library?.version
+
+  const summaries: Record<string, string> = {}
+  // Generate summaries object from the summaries file for later lookup
+  if (summariesFilePath) {
+    try {
+      const summariesContent = readFileSync(summariesFilePath, 'utf-8')
+      const data = JSON.parse(summariesContent)
+
+      data.forEach((item: { title: string; summary?: string }) => {
+        summaries[item.title] = item.summary || ''
+      })
+    } catch (error) {
+      console.warn('Could not load summaries file:', error)
+    }
+  }
+
+  let LlmsMarkdownContent = `# Instructure UI (InstUI) - React Component Library\n\n- version ${version} \n\n`
+  LlmsMarkdownContent += `- Instructure UI (InstUI) is a comprehensive React component library.\n\n`
+
+  // Add main Documentation section
+  LlmsMarkdownContent += `## Documentation\n\n`
+
+  // Add User Guides section
+  LlmsMarkdownContent += `### User Guides\n`
+
+  Object.entries(sections as Record<string, SectionData>).forEach(
+    ([sectionKey, sectionData]) => {
+      const sectionTitle = sectionData.title || sectionKey
+
+      // Only process these specific sections
+      if (!['Getting Started', 'Guides', 'Patterns'].includes(sectionTitle)) {
+        return
+      }
+
+      LlmsMarkdownContent += `#### ${sectionTitle}\n\n`
+
+      if (sectionData.docs && sectionData.docs.length > 0) {
+        const uniqueDocs = [...new Set(sectionData.docs)]
+        uniqueDocs.forEach((doc) => {
+          // Skip unnecessary documents
+          if (
+            doc === 'CODE_OF_CONDUCT' ||
+            doc === 'LICENSE' ||
+            doc.includes('upgrade-guide')
+          ) {
+            return
+          }
+          const displayName = doc
+            .replace(/([A-Z])/g, ' $1')
+            .replace(/-/g, ' ')
+            .trim()
+            .toLowerCase()
+            .replace(/^\w/, (char) => char.toUpperCase())
+
+          const summary = summaries[doc]
+          LlmsMarkdownContent += `- [${displayName}](${baseUrl}${doc}.md)${
+            summary ? `: ${summary}` : ''
+          }\n`
+        })
+      }
+      LlmsMarkdownContent += '\n'
+    }
+  )
+
+  // Add Components section under Documentation
+  LlmsMarkdownContent += `### Components\n\n`
+
+  const componentsSection = sections['components'] as SectionData | undefined
+  if (componentsSection) {
+    const allComponents = [...new Set(componentsSection.docs || [])]
+    allComponents.forEach((component) => {
+      const summary = summaries[component]
+      LlmsMarkdownContent += `- [${component}](${baseUrl}${component}.md)${
+        summary ? `: ${summary}` : ''
+      }\n`
+    })
+  }
+
+  // Process component subsections like Components/AI Components and Components/Utilities, skip deprecated
+  if (componentsSection?.sections && componentsSection.sections.length > 0) {
+    const subsections = componentsSection.sections
+    subsections.forEach((subsectionPath: string) => {
+      if (subsectionPath.toLowerCase().includes('deprecated')) return
+
+      const subsection = sections[subsectionPath] as SectionData | undefined
+      if (subsection && subsection.docs && subsection.docs.length > 0) {
+        const subsectionTitle = subsection.title
+        LlmsMarkdownContent += `\n#### ${subsectionTitle}\n\n`
+        // Avoid duplicates
+        const uniqueSubDocs = [...new Set(subsection.docs)]
+        uniqueSubDocs.forEach((doc) => {
+          const summary = summaries[doc]
+          LlmsMarkdownContent += `- [${doc}](${baseUrl}${doc}.md)${
+            summary ? `: ${summary}` : ''
+          }\n`
+        })
+      }
+    })
+  }
+
+  if (outputFilePath) {
+    writeFileSync(outputFilePath, LlmsMarkdownContent)
+  }
+
+  return LlmsMarkdownContent
+}
+
+export { generateAIAccessibleLlmsFile }
diff --git a/packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-markdowns.mts b/packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-markdowns.mts
diff --git a/packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json b/packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json
diff --git a/packages/__docs__/buildScripts/build-docs.mts b/packages/__docs__/buildScripts/build-docs.mts
