+
+
+
+
+
+ LLMs.txt
+AI-ready documentation endpoints generated from the BCC Component Library Storybook docs.
+
+
+
+
+
+
+
+
+
+ /llms.txt
+A concise index of public Storybook documentation pages. Use this endpoint when an AI assistant needs a quick, high-signal entry point to the most relevant docs.
+
+
+
+
+
+
+ /llms-full.txt
+A complete export of all public Storybook docs pages. Use this file when AI tooling needs full documentation coverage instead of a summarized index.
+
+
+
+
+
+ .md extension
+Append .md to any public docs URL to get a Markdown version of that page. This is useful for ingestion in AI workflows and external documentation tooling.
'); // Replace newlines with
+} + +function renderMarkdownTable(headers, rows) { + if (rows.length === 0) return ''; + + const lines = [ + `| ${headers.map(escapeMarkdownTableCell).join(' | ')} |`, + `| ${headers.map(() => '---').join(' | ')} |`, + ]; + + for (const row of rows) { + lines.push(`| ${row.map(escapeMarkdownTableCell).join(' | ')} |`); + } + + return lines.join('\n'); +} + +function renderTokenRowsMarkdown(rows) { + if (rows.length === 0) return ''; + + const kind = rows[0].kind; + + if (kind === 'color') { + return renderMarkdownTable( + ['Token', 'Description', 'Light value', 'Dark value', 'CSS variable', 'Tailwind class'], + rows.map(row => [ + `\`${row.token}\``, + row.description, + row.lightValue, + row.darkValue, + `\`${row.cssVariable}\``, + `\`${row.tailwindClass}\``, + ]) + ); + } + + if (kind === 'shadow') { + return renderMarkdownTable( + ['Token', 'Description', 'Light shadow', 'Dark shadow', 'CSS variable', 'Tailwind class'], + rows.map(row => [ + `\`${row.token}\``, + row.description, + row.lightValue, + row.darkValue, + `\`${row.cssVariable}\``, + `\`${row.tailwindClass}\``, + ]) + ); + } + + if (kind === 'preview') { + return renderMarkdownTable( + ['Token', 'Description', 'Preview', 'Tailwind class'], + rows.map(row => [`\`${row.token}\``, row.description, row.preview, `\`${row.tailwindClass}\``]) + ); + } + + if (kind === 'spacing') { + return renderMarkdownTable( + ['Token', 'Multiplier', 'REM', 'Pixels', 'Tailwind class'], + rows.map(row => [`\`${row.token}\``, row.multiplier, row.rem, row.px, `\`${row.tailwindClass}\``]) + ); + } + + return renderMarkdownTable( + ['Token', 'Description', 'Value', 'CSS variable', 'Tailwind class'], + rows.map(row => [ + `\`${row.token}\``, + row.description, + row.value, + row.cssVariable ? `\`${row.cssVariable}\`` : '', + `\`${row.tailwindClass}\``, + ]) + ); +} + +function renderObjectArrayTableMarkdown(table) { + const keys = []; + + for (const row of table.rows) { + for (const key of Object.keys(row)) { + if (!keys.includes(key)) keys.push(key); + } + } + + if (keys.length === 0) return ''; + + const title = `**${humanizeIdentifier(table.name)}**`; + const markdownTable = renderMarkdownTable( + keys.map(humanizeObjectKey), + table.rows.map(row => keys.map(key => row[key] ?? '')) + ); + + return `${title}\n\n${markdownTable}`; +} + +function extractArgDescriptions(source) { + const props = new Map(); + const argTypes = extractObjectAfter(source, 'argTypes:'); + if (!argTypes) return []; + + for (const entry of splitTopLevelEntries(argTypes)) { + const match = entry.match(/^([A-Za-z_$][\w$]*)\s*:\s*([\s\S]+)$/); + if (!match) continue; + + const [, propName, definition] = match; + if (propName === 'docs' || propName === 'description') continue; + + const descriptionMatch = definition.match(/description:\s*(['"`])([\s\S]*?)\1/); + const controlMatch = definition.match( + /control:\s*(?:\{\s*type:\s*(['"`])([\s\S]*?)\1[\s\S]*?\}|(['"`])([\s\S]*?)\3)/ + ); + const optionsMatch = definition.match(/options:\s*\[([\s\S]*?)\]/); + const defaultMatch = definition.match(/defaultValue:\s*\{[\s\S]*?summary:\s*(['"`])([\s\S]*?)\1/); + const typeMatch = definition.match(/type:\s*\{[\s\S]*?summary:\s*(['"`])([\s\S]*?)\1/); + + props.set(propName, { + description: descriptionMatch ? cleanInlineMarkdown(descriptionMatch[2]) : '', + control: cleanInlineMarkdown(controlMatch?.[2] ?? controlMatch?.[4] ?? ''), + options: cleanInlineMarkdown(optionsMatch?.[1]?.replace(/\s+/g, ' ') ?? ''), + defaultValue: cleanInlineMarkdown(defaultMatch?.[2] ?? ''), + typeSummary: cleanInlineMarkdown(typeMatch?.[2] ?? ''), + }); + } + + return Array.from(props.entries()).map(([name, values]) => ({ name, ...values })); +} + +function extractStoryNames(source) { + const names = new Set(); + const exportPattern = /export\s+const\s+([A-Z]\w*)\s*[:=]/g; + + for (const match of source.matchAll(exportPattern)) { + names.add(match[1]); + } + + return Array.from(names); +} + +function extractComponentName(source) { + const match = source.match(/\bcomponent:\s*([A-Za-z_$][\w$]*)/); + return match?.[1] ?? ''; +} + +function extractTopLevelParameters(source) { + const parameters = extractObjectAfter(source, 'parameters:'); + if (!parameters) return []; + + const values = []; + const componentDescription = parameters.match(/description:\s*\{[\s\S]*?component:\s*(['"`])([\s\S]*?)\1/); + if (componentDescription) { + values.push(`component description: ${cleanInlineMarkdown(componentDescription[2])}`); + } + + for (const entry of splitTopLevelEntries(parameters)) { + const match = entry.match(/^([A-Za-z_$][\w$]*)\s*:\s*([\s\S]+)$/); + if (!match) continue; + const [, key, value] = match; + if (key === 'docs') continue; + values.push(`${key}: ${cleanInlineMarkdown(value).slice(0, 180)}`); + } + + return values; +} + +function extractStoryDefinitions(source) { + const definitions = []; + const exportPattern = /export\s+const\s+([A-Z]\w*)\s*(?::[^=]+)?=\s*/g; + + for (const match of source.matchAll(exportPattern)) { + const storyName = match[1]; + const afterExportIndex = (match.index ?? 0) + match[0].length; + const objectStart = source.indexOf('{', afterExportIndex); + if (objectStart === -1) continue; + + const objectBody = extractObjectFromIndex(source, objectStart); + if (!objectBody) continue; + + const args = extractTopLevelProperty(objectBody, 'args'); + const parameters = extractTopLevelProperty(objectBody, 'parameters'); + const tokenRows = extractTokenRows(objectBody); + const doDont = extractDoDontGuidance(objectBody); + const rampTable = extractRampTable(source, objectBody); + const dataTables = extractObjectArrayTables(objectBody); + const templates = extractStringPropertyValues(objectBody, 'template'); + const sourceCodes = extractSourceCodeSnippets(objectBody); + const templateCodes = templates.map(template => + renderTemplateCodeSnippet( + template, + buildSetupContextForTemplate({ + source, + objectBody, + template, + args, + }) + ) + ); + + definitions.push({ + name: storyName, + args: summarizeObjectProperty(args), + parameters: summarizeObjectProperty(parameters, { skipKeys: ['docs'] }), + tokenRows, + doDont, + rampTable, + dataTables, + templates: templates.filter(Boolean), + sourceCodes: sourceCodes.filter(Boolean), + templateCodes: templateCodes.filter(Boolean), + }); + } + + return definitions; +} + +async function resolveStoryImportPath(sourceFilePath, importTarget) { + const resolvedBase = path.resolve(path.dirname(sourceFilePath), importTarget); + const candidates = [ + resolvedBase, + `${resolvedBase}.ts`, + `${resolvedBase}.tsx`, + `${resolvedBase}.js`, + `${resolvedBase}.jsx`, + ]; + + for (const candidate of candidates) { + const contents = await readFile(candidate, 'utf8').catch(() => ''); + if (contents) { + return { path: candidate, contents }; + } + } + + return null; +} + +function addStoryImport(importsByTarget, importTarget, binding) { + const entry = importsByTarget.get(importTarget) ?? { + importTarget, + namespaces: new Set(), + named: [], + }; + + if (binding.namespace) { + entry.namespaces.add(binding.namespace); + } + + if (binding.named) { + entry.named.push(binding.named); + } + + importsByTarget.set(importTarget, entry); +} + +function parseNamedStoryImports(specifier) { + return specifier + .split(',') + .map(part => part.trim()) + .filter(Boolean) + .map(part => { + const [exported, local] = part.split(/\s+as\s+/i).map(value => value.trim()); + return { exported, local: local || exported }; + }); +} + +function parseStoryImports(mdxSource) { + const importsByTarget = new Map(); + const namespacePattern = + /^\s*import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]*\.stories(?:\.[cm]?[jt]sx?)?)['"];?\s*$/gm; + const namedPattern = /^\s*import\s+\{([^}]+)\}\s+from\s+['"]([^'"]*\.stories(?:\.[cm]?[jt]sx?)?)['"];?\s*$/gm; + + for (const match of mdxSource.matchAll(namespacePattern)) { + const [, namespace, importTarget] = match; + addStoryImport(importsByTarget, importTarget, { namespace }); + } + + for (const match of mdxSource.matchAll(namedPattern)) { + const [, specifier, importTarget] = match; + for (const named of parseNamedStoryImports(specifier)) { + addStoryImport(importsByTarget, importTarget, { named }); + } + } + + return Array.from(importsByTarget.values()).map(entry => ({ + ...entry, + namespaces: Array.from(entry.namespaces), + })); +} + +async function loadReferencedStorySources(mdxSource, sourceFilePath) { + const imports = parseStoryImports(mdxSource); + + const resolved = []; + for (const storyImport of imports) { + const { importTarget } = storyImport; + const entry = await resolveStoryImportPath(sourceFilePath, importTarget); + if (entry) resolved.push({ ...entry, imports: [storyImport] }); + } + + return resolved; +} + +function normalizeStoryReference(storyRef) { + return String(storyRef).replace(/\s+/g, ''); +} + +function renderStoryContentMarkdown(story, { includeHeading = false, headingLevel = 3 } = {}) { + const lines = []; + const sourceCodes = story.sourceCodes ?? []; + const templateCodes = story.templateCodes ?? []; + const codeExamples = sourceCodes.length > 0 ? sourceCodes : templateCodes; + + if (includeHeading) { + lines.push(`${'#'.repeat(headingLevel)} ${humanizeIdentifier(story.name)}`, ''); + } + + if (story.doDont) { + lines.push(renderDoDontMarkdown(story.doDont), ''); + } else if (story.tokenRows.length > 0) { + lines.push(renderTokenRowsMarkdown(story.tokenRows), ''); + } else if (story.rampTable) { + lines.push(renderObjectArrayTableMarkdown(story.rampTable), ''); + } else if (story.dataTables.length > 0) { + for (const table of story.dataTables) { + lines.push(renderObjectArrayTableMarkdown(table), ''); + } + } + + if (story.args) lines.push(`- Args: ${story.args}`); + if (story.parameters) lines.push(`- Parameters: ${story.parameters}`); + if (story.args || story.parameters) lines.push(''); + + for (const snippet of codeExamples) { + lines.push('```vue', snippet, '```', ''); + } + + if (lines.length === 0 || (includeHeading && lines.length === 2)) { + lines.push(`> Visual example: ${humanizeIdentifier(story.name)}`, ''); + } + + return lines.join('\n').trim(); +} + +async function buildStoryMarkdownByRef(mdxSource, sourceFilePath) { + const references = await loadReferencedStorySources(mdxSource, sourceFilePath); + const storyMarkdownByRef = new Map(); + + for (const reference of references) { + const storyDefinitions = extractStoryDefinitions(reference.contents); + const storyDefinitionsByName = new Map(storyDefinitions.map(story => [story.name, story])); + + for (const storyImport of reference.imports) { + for (const namespace of storyImport.namespaces) { + for (const story of storyDefinitions) { + storyMarkdownByRef.set( + normalizeStoryReference(`${namespace}.${story.name}`), + renderStoryContentMarkdown(story) + ); + } + } + + for (const named of storyImport.named) { + const story = storyDefinitionsByName.get(named.exported); + if (!story) continue; + storyMarkdownByRef.set(normalizeStoryReference(named.local), renderStoryContentMarkdown(story)); + } + } + } + + return { references, storyMarkdownByRef }; +} + +async function renderStoryMarkdown(sourceFilePath, entry) { + const source = await readFile(sourceFilePath, 'utf8'); + const component = extractComponentName(source); + const descriptions = extractStoryDescriptions(source); + const props = extractArgDescriptions(source); + const stories = extractStoryNames(source); + const parameters = extractTopLevelParameters(source); + const storyDefinitions = extractStoryDefinitions(source); + const lines = []; + + if (descriptions.length > 0) { + lines.push(...descriptions, ''); + } else { + lines.push(`Documentation for ${entry.title}.`, ''); + } + + if (component) { + lines.push('## Component', '', `\`${component}\``, ''); + } + + if (parameters.length > 0) { + lines.push('## Parameters', ''); + for (const parameter of parameters) { + lines.push(`- ${parameter}`); + } + lines.push(''); + } + + if (props.length > 0) { + lines.push( + '## Props', + '', + '| Prop | Description | Type | Default | Control | Options |', + '| --- | --- | --- | --- | --- | --- |' + ); + for (const prop of props) { + lines.push( + `| \`${prop.name}\` | ${prop.description || '-'} | ${prop.typeSummary || '-'} | ${prop.defaultValue || '-'} | ${prop.control || '-'} | ${prop.options || '-'} |` + ); + } + lines.push(''); + } + + if (stories.length > 0) { + lines.push('## Stories', ''); + for (const storyName of stories) { + lines.push(`- ${humanizeIdentifier(storyName)}`); + } + lines.push(''); + } + + if (storyDefinitions.length > 0) { + lines.push('## Story Details', ''); + for (const story of storyDefinitions) { + lines.push(renderStoryContentMarkdown(story, { includeHeading: true }), ''); + } + } + + return lines.join('\n').trim(); +} + +function ensurePageHeader(entry, markdown) { + const source = trimDotSlash(entry.importPath); + const metadata = `> Source: \`${source}\`. Docs route: \`${docsRoute(entry.id)}\`.`; + const trimmed = markdown.trim(); + + if (trimmed.startsWith('# ')) { + return `${trimmed.replace(/^# .*(?:\n|$)/, match => `${match.trimEnd()}\n\n${metadata}\n\n`)}`.trim(); + } + + return `# ${entry.title}\n\n${metadata}\n\n${trimmed}`.trim(); +} + +function summarizeMarkdown(markdown, fallback) { + const lines = markdown + .split('\n') + .map(line => line.trim()) + .filter(Boolean) + .filter(line => !line.startsWith('#')) + .filter(line => !line.startsWith('> Source:')) + .filter(line => !line.startsWith('---')); + + const summary = + lines.find( + line => !line.startsWith('- ') && !line.startsWith('> Story example:') && !line.startsWith('> Visual example:') + ) ?? fallback; + return summary; +} + +async function renderPage(entry, cwd, baseUrl) { + const source = trimDotSlash(entry.importPath); + const sourceFilePath = path.resolve(cwd, source); + const workspaceRoot = `${cwd}${path.sep}`; + + if (!sourceFilePath.startsWith(workspaceRoot)) { + throw new Error(`Refusing to read docs source outside workspace: ${entry.importPath}`); + } + + const sourceMarkdown = source.endsWith('.mdx') + ? await renderMdxMarkdown(sourceFilePath) + : await renderStoryMarkdown(sourceFilePath, entry); + const markdown = `${ensurePageHeader(entry, sourceMarkdown)}\n`; + + return { + id: entry.id, + title: entry.title, + label: titleToLabel(entry.title), + section: sectionForTitle(entry.title), + source, + route: docsRoute(entry.id), + url: docsUrl(baseUrl, entry.id), + markdownRoute: markdownRoute(entry.id), + markdownUrl: markdownUrl(baseUrl, entry.id), + storybookUrl: storybookUrl(baseUrl, entry.id), + summary: summarizeMarkdown(markdown, `Documentation page for ${entry.title}.`), + markdown, + order: entry.order, + }; +} + +function llmsSummary(page, baseUrl) { + const base = normalizeBaseUrl(baseUrl); + return page.summary.replace(/\]\((\/(?:docs\/[^)#]+\.md|llms-full\.txt)(?:#[^)]+)?)\)/g, `](${base}$1)`); +} + +function renderLlmsEntry(page, baseUrl) { + return `- [${llmsLabel(page)}](${page.markdownUrl}): ${llmsSummary(page, baseUrl)}`; +} + +function llmsPageBuckets(pages) { + const startHerePages = pages + .filter(isStartHerePage) + .sort((left, right) => startHerePriority(left) - startHerePriority(right) || compareEntries(left, right)); + + const startHereIds = new Set(startHerePages.map(page => page.id)); + const groupedSections = groupBySection(pages.filter(page => !startHereIds.has(page.id))).sort(([left], [right]) => { + const priorityDiff = sectionPriority(left) - sectionPriority(right); + return priorityDiff || left.localeCompare(right); + }); + + return [ + { name: 'Start here', pages: startHerePages }, + ...groupedSections.map(([section, group]) => { + return { + name: sectionHeading(section), + pages: group.slice().sort(compareEntries), + }; + }), + ]; +} + +function validationSectionBuckets(pages) { + return llmsPageBuckets(pages).map(bucket => ({ + name: bucket.name, + labels: bucket.pages.map(llmsLabel), + })); +} + +function renderLlmsTxt(pages, baseUrl = DEFAULT_BASE_URL) { + const sections = llmsPageBuckets(pages) + .map(bucket => { + if (bucket.pages.length === 0) return ''; + + const links = bucket.pages.map(page => renderLlmsEntry(page, baseUrl)).join('\n'); + return `## ${bucket.name}\n\n${links}`; + }) + .filter(Boolean) + .join('\n\n'); + + const fullDocumentationSection = `## Full documentation\n\n- [llms-full.txt](${normalizeBaseUrl(baseUrl)}/llms-full.txt): Complete export of all public Storybook docs pages.`; + + return `# BCC Component Library\n\n> Vue 3 component library built on PrimeVue and BCC design tokens.\n\n${sections}\n\n${fullDocumentationSection}\n`; +} + +function renderLlmsFullTxt(pages) { + const contents = pages + .slice() + .sort(compareEntries) + .map(page => { + return `---\n\n${page.markdown.trim()}\n\nMarkdown URL: ${page.markdownUrl}\nStorybook URL: ${page.storybookUrl}`; + }) + .join('\n\n'); + + return `# BCC Component Library Full Documentation\n\n> Complete AI-ready Markdown export for all public Storybook docs pages.\n\n${contents}\n`; +} + +async function removeStaleGeneratedMarkdown(outputDir) { + const rootEntries = await readdir(outputDir, { withFileTypes: true }).catch(() => []); + + await Promise.all( + rootEntries + .filter(entry => entry.isFile() && entry.name.endsWith('--docs.md')) + .map(entry => unlink(path.join(outputDir, entry.name))) + ); + + const docsDir = path.join(outputDir, 'docs'); + const docsEntries = await readdir(docsDir, { withFileTypes: true }).catch(() => []); + + await Promise.all( + docsEntries + .filter(entry => entry.isFile() && entry.name.endsWith('.md')) + .map(entry => unlink(path.join(docsDir, entry.name))) + ); +} + +async function writeOutputs(outputDir, pages, baseUrl) { + const docsDir = path.join(outputDir, 'docs'); + await mkdir(docsDir, { recursive: true }); + await removeStaleGeneratedMarkdown(outputDir); + + const llmsTxt = renderLlmsTxt(pages, baseUrl); + const llmsFullTxt = renderLlmsFullTxt(pages); + + await Promise.all([ + writeFile(path.join(outputDir, 'llms.txt'), llmsTxt, 'utf8'), + writeFile(path.join(outputDir, 'llms-full.txt'), llmsFullTxt, 'utf8'), + ...pages.map(page => writeFile(path.join(docsDir, `${page.id}.md`), `${UTF8_BOM}${page.markdown}`, 'utf8')), + ]); + + return { llmsTxt, llmsFullTxt }; +} + +async function main() { + const cwd = process.cwd(); + const outputDir = path.resolve(cwd, process.env.STORYBOOK_OUT_DIR ?? DEFAULT_OUTPUT_DIR); + const baseUrl = normalizeBaseUrl(process.env.LLMS_BASE_URL ?? DEFAULT_BASE_URL); + const indexJsonPath = path.join(outputDir, 'index.json'); + const rawIndex = await readFile(indexJsonPath, 'utf8').catch(error => { + throw new Error(`Unable to read ${indexJsonPath}. Run Storybook build before generating AI docs. ${error.message}`); + }); + const manifest = JSON.parse(rawIndex); + const entries = Object.values(manifest.entries ?? {}).map((entry, order) => ({ ...entry, order })); + const docsEntries = entries.filter(isPublicDocsEntry).sort(compareEntries); + const pages = await Promise.all(docsEntries.map(entry => renderPage(entry, cwd, baseUrl))); + + const outputs = await writeOutputs(outputDir, pages, baseUrl); + await validateGeneratedOutputs({ + outputDir, + pages, + baseUrl, + ...outputs, + sectionBuckets: validationSectionBuckets(pages), + }); + + console.log(`Generated AI docs in ${outputDir}`); + console.log(`Base URL: ${baseUrl}`); + console.log(`Docs pages: ${pages.length}`); + console.log('Outputs: llms.txt, llms-full.txt, docs/*.md'); + console.log('Quality check: passed'); +} + +export { cleanInlineMarkdown, extractStoryDefinitions, mdxToMarkdown, renderStoryContentMarkdown, renderStoryMarkdown }; + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + main().catch(error => { + console.error(error); + process.exitCode = 1; + }); +} diff --git a/component-library/scripts/generate-llms-files.spec.ts b/component-library/scripts/generate-llms-files.spec.ts new file mode 100644 index 000000000..41df8b08c --- /dev/null +++ b/component-library/scripts/generate-llms-files.spec.ts @@ -0,0 +1,128 @@ +import { readFileSync } from 'node:fs'; +import { describe, expect, test } from 'vitest'; +import { + cleanInlineMarkdown, + extractStoryDefinitions, + mdxToMarkdown, + renderStoryContentMarkdown, +} from './generate-llms-files.mjs'; + +function storyMarkdown(relativePath: string, storyName: string): string { + const source = readFileSync(new URL(relativePath, import.meta.url), 'utf8'); + const story = extractStoryDefinitions(source).find(definition => definition.name === storyName); + + if (!story) { + throw new Error(`Missing story ${storyName} in ${relativePath}`); + } + + return renderStoryContentMarkdown(story, { includeHeading: true }); +} + +function expectVueCodeBlock(markdown: string) { + expect(markdown).toContain('```vue'); + expect(markdown).not.toMatch(/^> Visual example:/m); +} + +describe('llms Storybook story code examples', () => { + test('labels tw table columns as Tailwind in generated markdown', () => { + const markdown = storyMarkdown('../docs/foundations/Typography.stories.ts', 'HeadingScale'); + + expect(markdown).toContain('| Token | Tailwind |'); + expect(markdown).not.toContain('| Token | Tw |'); + }); + + test('uses parameters.docs.source.code when present', () => { + const markdown = storyMarkdown('../src/components/wrapped/BccMessage.stories.ts', 'Severities'); + + expectVueCodeBlock(markdown); + expect(markdown).toContain(''); + expect(markdown).toContain('
Safe
'
+ );
+
+ expect(markdown).toBe('Safe\nText');
+ expect(markdown).not.toContain('alert');
+ expect(markdown).not.toContain('Text