feat(build): generate llms.txt via doc-kit (#201)

* feat(build): generate llms.txt via doc-kit

- add the llms-txt target with a webpack-specific template
- link entries to raw markdown pages and copy the .md sources into out/
- drop empty entries produced by JSX-driven pages (home, blog index)

* Apply suggestion from @bjohansebas

Author: bjohansebas

scripts/html/doc-kit.config.mjs

@@ -43,6 +43,11 @@ export default {
     generateIndexPage: false,
     generateAllPage: false,
   },
+  'llms-txt': {
+    templatePath: join(ROOT, 'scripts/html/llms-template.txt'),
+    pageURL: `${BASE_URL.replace(/\/$/, '')}{path}.md`,
+    output: VERSION ? `./out/docs/api/${MAJOR_VERSION}` : './out',
+  },
   web: {
     project: 'webpack',
     useAbsoluteURLs: true,

scripts/html/index.mjs

@@ -1,9 +1,23 @@
 import { execFile } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { cp, readFile, writeFile } from 'node:fs/promises';
+import { statSync } from 'node:fs';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
 
+// TODO: Have doc-kit understand that some pages don't have meaningful information
+// The llms-txt generator lists every page with a depth-1 heading. JSX-driven
+// pages like the homepage produce entries with no title or description — drop
+// them, they carry no information for LLMs.
+const cleanLlmsTxt = async path => {
+  const content = await readFile(path, 'utf8');
+  const cleaned = content
+    .split('\n')
+    .filter(line => !line.startsWith('- []('))
+    .join('\n');
+  await writeFile(path, cleaned);
+};
+
 const runDocKit = version =>
   execFileAsync(
     'npx',
@@ -16,6 +30,8 @@ const runDocKit = version =>
       'web',
       '-t',
       'orama-db',
+      '-t',
+      'llms-txt',
       '--config-file',
       './scripts/html/doc-kit.config.mjs',
     ],
@@ -35,5 +51,14 @@ const versions = JSON.parse(await readFile('./versions.json'));
 
 for (const version of versions) {
   await runDocKit(version);
+  await cleanLlmsTxt(`./out/docs/api/v${version.match(/\d+/)[0]}.x/llms.txt`);
 }
 await runDocKit();
+await cleanLlmsTxt('./out/llms.txt');
+
+// Publish the markdown sources next to the rendered pages so the llms.txt
+// links (`{path}.md`) resolve to LLM-friendly raw markdown.
+await cp('./pages', './out', {
+  recursive: true,
+  filter: source => statSync(source).isDirectory() || source.endsWith('.md'),
+});

scripts/html/llms-template.txt

@@ -0,0 +1,8 @@
+# webpack Documentation
+
+> webpack is a static module bundler for modern JavaScript applications. It builds a dependency graph from one or more entry points and combines every module your project needs into one or more bundles, and it can transform, bundle, or package just about any resource or asset.
+
+Below are the sections of the webpack documentation. Look out especially towards the links that point towards guidance/introduction to the structure of this documentation.
+
+## Documentation
+