diff --git a/scripts/html/doc-kit.config.mjs b/scripts/html/doc-kit.config.mjs index 7606bb74..71924db4 100644 --- a/scripts/html/doc-kit.config.mjs +++ b/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, diff --git a/scripts/html/index.mjs b/scripts/html/index.mjs index d2ff70c1..7bd0c835 100644 --- a/scripts/html/index.mjs +++ b/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'), +}); diff --git a/scripts/html/llms-template.txt b/scripts/html/llms-template.txt new file mode 100644 index 00000000..6672a249 --- /dev/null +++ b/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 +