Add llms.txt and llms-full.txt

Author: roxblnfk

.vitepress/config.mts

@@ -1,5 +1,6 @@
 import { defineConfig, HeadConfig } from 'vitepress'
 import { generateRss, rssPlugin } from './rss'
+import { generateLlms, llmsPlugin } from './llms'
 import { isBlogPath } from './locales'
 
 const baseUrl = 'https://php-testo.github.io'
@@ -14,7 +15,7 @@ export default defineConfig({
   ignoreDeadLinks: [/feed\.xml$/],
 
   vite: {
-    plugins: [rssPlugin()],
+    plugins: [rssPlugin(), llmsPlugin()],
   },
 
   head: [
@@ -26,7 +27,10 @@ gtag('js', new Date());
 gtag('config', 'G-VYGDN3X0PR');`],
   ],
 
-  buildEnd: generateRss,
+  buildEnd: async (config) => {
+    await generateRss(config)
+    await generateLlms(config)
+  },
 
   locales: {
     root: {

.vitepress/llms.ts

@@ -0,0 +1,205 @@
+import { writeFileSync, mkdirSync, readdirSync, readFileSync, existsSync } from 'fs'
+import path from 'path'
+import { SiteConfig } from 'vitepress'
+import type { Plugin } from 'vite'
+// @ts-ignore
+import matter from 'gray-matter'
+import { llmsConfig } from '../llms.config'
+
+interface PageInfo {
+  title: string
+  llms_description: string
+  url: string
+  srcPath: string
+  content: string
+  section: 'docs' | 'optional'
+}
+
+function extractH1(content: string): string | null {
+  const match = content.match(/^#\s+(.+)$/m)
+  return match ? match[1].trim() : null
+}
+
+function readPages(srcDir: string): PageInfo[] {
+  const pages: PageInfo[] = []
+
+  const docsDir = path.join(srcDir, 'docs')
+  if (existsSync(docsDir)) {
+    for (const file of readdirSync(docsDir).filter(f => f.endsWith('.md'))) {
+      const filePath = path.join(docsDir, file)
+      const raw = readFileSync(filePath, 'utf-8')
+      const { data: fm, content } = matter(raw)
+
+      if (fm.llms === false || !fm.llms_description) continue
+
+      const slug = file.replace(/\.md$/, '')
+      const llmsValue = fm.llms ?? true
+      pages.push({
+        title: fm.title || extractH1(content) || slug,
+        llms_description: fm.llms_description,
+        url: `/docs/${slug}`,
+        srcPath: `llm/docs/${file}`,
+        content: content.trim(),
+        section: llmsValue === 'optional' ? 'optional' : 'docs',
+      })
+    }
+  }
+
+  return pages
+}
+
+function getSidebarPaths(config: SiteConfig): string[] {
+  const paths: string[] = []
+
+  const sidebar =
+    (config.site.locales?.root as any)?.themeConfig?.sidebar ??
+    config.site.themeConfig?.sidebar ??
+    {}
+
+  function extract(items: any[]) {
+    if (!Array.isArray(items)) return
+    for (const item of items) {
+      if (item.link) paths.push(item.link)
+      if (item.items) extract(item.items)
+    }
+  }
+
+  for (const section of Object.values(sidebar)) {
+    if (Array.isArray(section)) extract(section)
+  }
+
+  return paths
+}
+
+function sortPages(pages: PageInfo[], sidebarPaths: string[]): PageInfo[] {
+  const order = new Map(sidebarPaths.map((p, i) => [p, i]))
+
+  return [...pages].sort((a, b) => {
+    const ia = order.get(a.url) ?? 9999
+    const ib = order.get(b.url) ?? 9999
+    return ia - ib || a.url.localeCompare(b.url)
+  })
+}
+
+function buildLlmsTxt(pages: PageInfo[]): string {
+  const { title, summary, details, baseUrl, docsSection, optionalSection } = llmsConfig
+
+  const docs = pages.filter(p => p.section === 'docs')
+  const optional = pages.filter(p => p.section === 'optional')
+
+  const lines: string[] = [
+    `# ${title}`,
+    '',
+    `> ${summary}`,
+    '',
+    ...details.map(d => `- ${d}`),
+    '',
+  ]
+
+  if (docs.length > 0) {
+    lines.push(`## ${docsSection}`, '')
+    for (const p of docs) {
+      lines.push(`- [${p.title}](${baseUrl}/${p.srcPath}): ${p.llms_description}`)
+    }
+    lines.push('')
+  }
+
+  if (optional.length > 0) {
+    lines.push(`## ${optionalSection}`, '')
+    for (const p of optional) {
+      lines.push(`- [${p.title}](${baseUrl}/${p.srcPath}): ${p.llms_description}`)
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+function buildLlmsFullTxt(pages: PageInfo[]): string {
+  const { title, summary, details } = llmsConfig
+
+  const lines: string[] = [
+    `# ${title}`,
+    '',
+    `> ${summary}`,
+    '',
+    ...details.map(d => `- ${d}`),
+  ]
+
+  for (const page of pages) {
+    const startsWithH1 = /^#\s+/.test(page.content)
+    lines.push('', '---', '')
+    if (!startsWithH1) {
+      lines.push(`# ${page.title}`, '')
+    }
+    lines.push(page.content)
+  }
+
+  lines.push('')
+  return lines.join('\n')
+}
+
+// Build-time generation (called from buildEnd)
+export async function generateLlms(config: SiteConfig) {
+  const pages = sortPages(readPages(config.srcDir), getSidebarPaths(config))
+
+  // Per-page .md files
+  for (const page of pages) {
+    const outPath = path.join(config.outDir, page.srcPath)
+    mkdirSync(path.dirname(outPath), { recursive: true })
+    writeFileSync(outPath, page.content + '\n')
+  }
+
+  writeFileSync(path.join(config.outDir, 'llms.txt'), buildLlmsTxt(pages))
+  writeFileSync(path.join(config.outDir, 'llms-full.txt'), buildLlmsFullTxt(pages))
+
+  console.log(`✓ llms.txt generated (${pages.length} docs)`)
+  console.log(`✓ llms-full.txt generated`)
+  console.log(`✓ ${pages.length} per-page .md files generated`)
+}
+
+// Vite plugin for dev server
+export function llmsPlugin(): Plugin {
+  let docsRoot: string
+
+  return {
+    name: 'vitepress-llms-dev',
+    configResolved(config) {
+      docsRoot = config.root
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const url = req.url || ''
+
+        if (url === '/llms.txt') {
+          const pages = sortPages(readPages(docsRoot), [])
+          res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+          res.end(buildLlmsTxt(pages))
+          return
+        }
+
+        if (url === '/llms-full.txt') {
+          const pages = sortPages(readPages(docsRoot), [])
+          res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+          res.end(buildLlmsFullTxt(pages))
+          return
+        }
+
+        // Serve per-page .md files
+        const mdMatch = url.match(/^\/llm\/docs\/(.+\.md)$/)
+        if (mdMatch) {
+          const filePath = path.join(docsRoot, 'docs', mdMatch[1])
+          if (existsSync(filePath)) {
+            const raw = readFileSync(filePath, 'utf-8')
+            const { content } = matter(raw)
+            res.setHeader('Content-Type', 'text/markdown; charset=utf-8')
+            res.end(content.trim() + '\n')
+            return
+          }
+        }
+
+        next()
+      })
+    },
+  }
+}

CLAUDE.md

@@ -79,6 +79,35 @@ author: Author Name
   - `outline: false` — hide outline completely
   - `outline: 2` — show only h2
 
+## llms.txt
+
+Testo provides `llms.txt` for AI agents. Only `docs/` pages are included — blog posts are excluded from llms generation entirely (no llms frontmatter in blog files).
+
+**Manifest:** `llms.config.ts` — project-level metadata (title, summary, key facts, base URL). Edit when project description or key facts change.
+
+**Generator:** `.vitepress/llms.ts` — builds `llms.txt`, `llms-full.txt`, and per-page `.md` files during `buildEnd`. Only scans `docs/` directory.
+
+**Frontmatter fields (English `docs/` pages only, not `ru/` or `blog/`):**
+
+```yaml
+---
+llms: true              # default — included in "Docs" section
+llms: "optional"        # included in "Optional" section (secondary content)
+llms: false             # excluded from llms.txt
+llms_description: "Technical description of what LLM learns from this page"
+---
+```
+
+- `llms` — controls inclusion. Default is `true` (can be omitted). `"optional"` for secondary content, `false` to exclude
+- `llms_description` — short, technical description for LLM context. Lists key entities and concepts, not marketing text. Required for all included pages
+
+**Guidelines for `llms_description`:**
+- List specific classes, attributes, methods — not vague descriptions
+- Example: `"#[BeforeEach], #[AfterEach], #[BeforeAll], #[AfterAll] lifecycle hooks, execution order, priority"`
+- NOT: `"Learn about test lifecycle management"`
+
+**When adding new doc pages:** add `llms_description` to the English version frontmatter. Do NOT add llms frontmatter to blog posts.
+
 ## VitePress Commands
 
 ```bash

docs/cli-reference.md

@@ -1,3 +1,7 @@
+---
+llms_description: "CLI commands and flags: testo run, --config, --teamcity, --suite, --path, --filter, filter combination logic, exit codes"
+---
+
 # Command Line Interface
 
 This document describes the command line interface for Testo.

docs/data-providers.md

@@ -1,3 +1,7 @@
+---
+llms_description: "Parameterized tests: #[DataSet], #[DataProvider] with callables, DataZip (pairing), DataCross (cartesian product), DataUnion (merging), nested combinations"
+---
+
 # Data Providers
 
 Data providers let you run one test with different sets of input data. Each set runs as a separate test.

docs/events.md

@@ -1,3 +1,7 @@
+---
+llms_description: "PSR-14 event system: TestSuite/TestCase/Test event hierarchy, lifecycle event ordering, polymorphic listeners, custom dispatchers"
+---
+
 # Events
 
 Testo emits events throughout the test execution lifecycle. Events are your primary extension point for customizing test behavior, collecting metrics, or integrating with external tools.

docs/filtering.md

@@ -1,3 +1,7 @@
+---
+llms_description: "Filter class API, name/path/suite filters, OR/AND combination logic, 5-stage filtering pipeline, pattern matching behavior, DataProvider indices"
+---
+
 # Test Filtering
 
 This document describes the business logic of test filtering in Testo.

docs/getting-started.md

@@ -1,3 +1,7 @@
+---
+llms_description: "Installation via Composer, testo.php configuration, writing first test class, running tests, IDE plugin setup"
+---
+
 # Getting Started
 
 

docs/inline-tests.md

@@ -1,3 +1,7 @@
+---
+llms_description: "#[TestInline] attribute for testing methods in-place, private method testing, custom assertions, named arguments"
+---
+
 # Inline Tests
 
 Inline tests let you write test cases directly on the method being tested using the `#[TestInline]` attribute. No separate test class needed.

docs/lifecycle.md

@@ -1,3 +1,7 @@
+---
+llms_description: "#[BeforeEach], #[AfterEach], #[BeforeAll], #[AfterAll] lifecycle hooks, execution order, priority, class instantiation behavior"
+---
+
 # Lifecycle
 
 Lifecycle attributes define setup and teardown methods that run automatically at specific points during test execution.