From d7324d0fa3ecab34ebe6cdc5b63616ae80421957 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Thu, 7 May 2026 10:40:31 -0400 Subject: [PATCH 1/9] docs: update llms.txt files and register site with context7 --- .gitignore | 1 + apps/docs/markdown-pages/docs/manual/llms.mdx | 24 +++- apps/docs/markdown-pages/docs/react/llms.mdx | 24 +++- apps/docs/public/docs/context7.json | 4 + apps/docs/public/llms/manual/template.mdx | 24 +++- apps/docs/public/llms/manual/template.txt | 21 ++- apps/docs/public/llms/react/template.mdx | 24 +++- apps/docs/public/llms/react/template.txt | 23 ++- .../scripts/__tests__/generate-llms.test.mjs | 135 ++++++++++++++++++ apps/docs/scripts/generate_llms.res | 94 ++++++++++-- apps/docs/src/bindings/Node.res | 1 + 11 files changed, 329 insertions(+), 46 deletions(-) create mode 100644 apps/docs/public/docs/context7.json create mode 100644 apps/docs/scripts/__tests__/generate-llms.test.mjs diff --git a/.gitignore b/.gitignore index 0677c6b6a..95a1af168 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ apps/docs/scripts/generate_*.jsx apps/docs/scripts/LogAlgoliaEnvStatus.jsx # Generated via generate-llms script +apps/docs/public/llms.txt apps/docs/public/llms/manual/**/llm*.txt apps/docs/public/llms/react/**/llm*.txt apps/docs/markdown-pages/docs/**/**/llms.mdx diff --git a/apps/docs/markdown-pages/docs/manual/llms.mdx b/apps/docs/markdown-pages/docs/manual/llms.mdx index 7e73b6153..4c2b43ed9 100644 --- a/apps/docs/markdown-pages/docs/manual/llms.mdx +++ b/apps/docs/markdown-pages/docs/manual/llms.mdx @@ -10,16 +10,26 @@ order: 4 We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications. -Currently, we have the following files... +Current ReScript manual version: `v12`. -- [/llms/manual/llms.txt](/llms/manual/llms.txt) — a list of the available files for ReScript language. -- [/llms/manual/llm-full.txt](/llms/manual/llm-full.txt) — complete documentation for ReScript language. -- [/llms/manual/llm-small.txt](/llms/manual/llm-small.txt) — compressed version of the former, without examples. +The root `/llms.txt` file is the default entry point and always describes the current stable manual. Use the versioned files under `/llms/manual/v12/` when you want a stable path for this manual version. -...and package-level documentation: +## Default Current Files -- [/docs/react/llms](../react/llms.mdx) — the LLms documentation for ReScript React. +- [/llms.txt](/llms.txt) - a list of the available files for the current ReScript language manual. +- [/llms/manual/llm-full.txt](/llms/manual/llm-full.txt) - complete current documentation for the ReScript language. +- [/llms/manual/llm-small.txt](/llms/manual/llm-small.txt) - abridged current documentation without detailed examples. + +## Versioned Files + +- [/llms/manual/v12/llms.txt](/llms/manual/v12/llms.txt) - a list of the available files for ReScript `v12`. +- [/llms/manual/v12/llm-full.txt](/llms/manual/v12/llm-full.txt) - complete documentation for ReScript `v12`. +- [/llms/manual/v12/llm-small.txt](/llms/manual/v12/llm-small.txt) - abridged documentation for ReScript `v12`. + +## Package Documentation + +- [/docs/react/llms](../react/llms.mdx) - the LLM documentation for ReScript React. ## Notes -- The content is automatically generated from the same source as the official documentation for the specific version +- The content is automatically generated from the same source as the official documentation for the specific version. diff --git a/apps/docs/markdown-pages/docs/react/llms.mdx b/apps/docs/markdown-pages/docs/react/llms.mdx index de3672cd5..2b701055a 100644 --- a/apps/docs/markdown-pages/docs/react/llms.mdx +++ b/apps/docs/markdown-pages/docs/react/llms.mdx @@ -9,16 +9,26 @@ section: "Overview" We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications. -Currently, we have the following files... +Current ReScript React documentation channel: `latest`. -- [/llms/react/llms.txt](/llms/react/llms.txt) — a list of the available files for ReScript React. -- [/llms/react/llms-full.txt](/llms/react/llm-full.txt) — complete documentation for ReScript React. -- [/llms/react/llms-small.txt](/llms/react/llm-small.txt) — compressed version of the former, without examples for ReScript React. +The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the named files under `/llms/react/latest/` when you want an explicit path for the docs channel generated by this build. -...and the language documentation: +## Default Current Files -- [/docs/manual/llms](../manual/llms.mdx) — the LLms documentation for ReScript. +- [/llms/react/llms.txt](/llms/react/llms.txt) - a list of the available files for the current ReScript React docs. +- [/llms/react/llm-full.txt](/llms/react/llm-full.txt) - complete current documentation for ReScript React. +- [/llms/react/llm-small.txt](/llms/react/llm-small.txt) - abridged current documentation without detailed examples. + +## Named Files + +- [/llms/react/latest/llms.txt](/llms/react/latest/llms.txt) - a list of the available files for ReScript React `latest`. +- [/llms/react/latest/llm-full.txt](/llms/react/latest/llm-full.txt) - complete documentation for ReScript React `latest`. +- [/llms/react/latest/llm-small.txt](/llms/react/latest/llm-small.txt) - abridged documentation for ReScript React `latest`. + +## Language Documentation + +- [/llms.txt](/llms.txt) - the LLM documentation for ReScript. ## Notes -- The content is automatically generated from the same source as the official documentation for the specific version +- The content is automatically generated from the same source as the official documentation for the specific version. diff --git a/apps/docs/public/docs/context7.json b/apps/docs/public/docs/context7.json new file mode 100644 index 000000000..8a51d41b1 --- /dev/null +++ b/apps/docs/public/docs/context7.json @@ -0,0 +1,4 @@ +{ + "url": "https://context7.com/websites/rescript-lang", + "public_key": "pk_dEopRkFptH4ndnTyOuXEb" +} diff --git a/apps/docs/public/llms/manual/template.mdx b/apps/docs/public/llms/manual/template.mdx index 7e73b6153..bd0481a5c 100644 --- a/apps/docs/public/llms/manual/template.mdx +++ b/apps/docs/public/llms/manual/template.mdx @@ -10,16 +10,26 @@ order: 4 We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications. -Currently, we have the following files... +Current ReScript manual version: ``. -- [/llms/manual/llms.txt](/llms/manual/llms.txt) — a list of the available files for ReScript language. -- [/llms/manual/llm-full.txt](/llms/manual/llm-full.txt) — complete documentation for ReScript language. -- [/llms/manual/llm-small.txt](/llms/manual/llm-small.txt) — compressed version of the former, without examples. +The root `/llms.txt` file is the default entry point and always describes the current stable manual. Use the versioned files under `/llms/manual//` when you want a stable path for this manual version. -...and package-level documentation: +## Default Current Files -- [/docs/react/llms](../react/llms.mdx) — the LLms documentation for ReScript React. +- [/llms.txt](/llms.txt) - a list of the available files for the current ReScript language manual. +- [/llms/manual/llm-full.txt](/llms/manual/llm-full.txt) - complete current documentation for the ReScript language. +- [/llms/manual/llm-small.txt](/llms/manual/llm-small.txt) - abridged current documentation without detailed examples. + +## Versioned Files + +- [/llms/manual//llms.txt](/llms/manual//llms.txt) - a list of the available files for ReScript ``. +- [/llms/manual//llm-full.txt](/llms/manual//llm-full.txt) - complete documentation for ReScript ``. +- [/llms/manual//llm-small.txt](/llms/manual//llm-small.txt) - abridged documentation for ReScript ``. + +## Package Documentation + +- [/docs/react/llms](../react/llms.mdx) - the LLM documentation for ReScript React. ## Notes -- The content is automatically generated from the same source as the official documentation for the specific version +- The content is automatically generated from the same source as the official documentation for the specific version. diff --git a/apps/docs/public/llms/manual/template.txt b/apps/docs/public/llms/manual/template.txt index 9d4b3ba71..b26355f60 100644 --- a/apps/docs/public/llms/manual/template.txt +++ b/apps/docs/public/llms/manual/template.txt @@ -4,8 +4,21 @@ ## Documentation Sets -- [Complete documentation](https://rescript-lang.org/llms/manual//llm-full.txt): The complete ReScript documentation including all examples and additional content -- [Abridged documentation](https://rescript-lang.org/llms/manual//llm-small.txt): A minimal version of the ReScript documentation, with the essential content for quick reference +Current ReScript manual version: . + +The root `/llms.txt` file is the default entry point and always describes the current stable manual. Use the versioned files under `/llms/manual//` when you want a stable path for this manual version. + +### Default Current Files + +- [LLMs index](https://rescript-lang.org/llms.txt): This file +- [Complete current documentation](https://rescript-lang.org/llms/manual/llm-full.txt): The complete current ReScript documentation including all examples and additional content +- [Abridged current documentation](https://rescript-lang.org/llms/manual/llm-small.txt): A minimal current version of the ReScript documentation, with the essential content for quick reference + +### Versioned Files + +- [ LLMs index](https://rescript-lang.org/llms/manual//llms.txt): This file for ReScript +- [ complete documentation](https://rescript-lang.org/llms/manual//llm-full.txt): The complete ReScript documentation including all examples and additional content +- [ abridged documentation](https://rescript-lang.org/llms/manual//llm-small.txt): A minimal ReScript reference with the essential content ## Individual Package Documentation @@ -13,7 +26,7 @@ ## Notes -- The abridged documentation excludes the detailed examples, and supplementary information +- The abridged documentation excludes the detailed examples and supplementary information - The complete documentation includes all content from the official documentation - Package-specific documentation files contain only the content relevant to that package -- The content is automatically generated from the same source as the official documentation for the specific version \ No newline at end of file +- The content is automatically generated from the same source as the official documentation for the specific version diff --git a/apps/docs/public/llms/react/template.mdx b/apps/docs/public/llms/react/template.mdx index de3672cd5..5783e83a1 100644 --- a/apps/docs/public/llms/react/template.mdx +++ b/apps/docs/public/llms/react/template.mdx @@ -9,16 +9,26 @@ section: "Overview" We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications. -Currently, we have the following files... +Current ReScript React documentation channel: ``. -- [/llms/react/llms.txt](/llms/react/llms.txt) — a list of the available files for ReScript React. -- [/llms/react/llms-full.txt](/llms/react/llm-full.txt) — complete documentation for ReScript React. -- [/llms/react/llms-small.txt](/llms/react/llm-small.txt) — compressed version of the former, without examples for ReScript React. +The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the named files under `/llms/react//` when you want an explicit path for the docs channel generated by this build. -...and the language documentation: +## Default Current Files -- [/docs/manual/llms](../manual/llms.mdx) — the LLms documentation for ReScript. +- [/llms/react/llms.txt](/llms/react/llms.txt) - a list of the available files for the current ReScript React docs. +- [/llms/react/llm-full.txt](/llms/react/llm-full.txt) - complete current documentation for ReScript React. +- [/llms/react/llm-small.txt](/llms/react/llm-small.txt) - abridged current documentation without detailed examples. + +## Named Files + +- [/llms/react//llms.txt](/llms/react//llms.txt) - a list of the available files for ReScript React ``. +- [/llms/react//llm-full.txt](/llms/react//llm-full.txt) - complete documentation for ReScript React ``. +- [/llms/react//llm-small.txt](/llms/react//llm-small.txt) - abridged documentation for ReScript React ``. + +## Language Documentation + +- [/llms.txt](/llms.txt) - the LLM documentation for ReScript. ## Notes -- The content is automatically generated from the same source as the official documentation for the specific version +- The content is automatically generated from the same source as the official documentation for the specific version. diff --git a/apps/docs/public/llms/react/template.txt b/apps/docs/public/llms/react/template.txt index d4f225f2f..39da43f9a 100644 --- a/apps/docs/public/llms/react/template.txt +++ b/apps/docs/public/llms/react/template.txt @@ -4,16 +4,29 @@ ## ReScript React Documentation -- [Complete documentation](https://rescript-lang.org/llms/react//llm-full.txt): The complete ReScript React documentation including all examples and additional content -- [Abridged documentation](https://rescript-lang.org/llms/react//llm-small.txt): A minimal version of the ReScript React documentation, with the essential content for quick reference +Current ReScript React documentation channel: . + +The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the named files under `/llms/react//` when you want an explicit path for the docs channel generated by this build. + +### Default Current Files + +- [LLMs index](https://rescript-lang.org/llms/react/llms.txt): This file +- [Complete current documentation](https://rescript-lang.org/llms/react/llm-full.txt): The complete current ReScript React documentation including all examples and additional content +- [Abridged current documentation](https://rescript-lang.org/llms/react/llm-small.txt): A minimal current version of the ReScript React documentation, with the essential content for quick reference + +### Named Files + +- [ LLMs index](https://rescript-lang.org/llms/react//llms.txt): This file for ReScript React +- [ complete documentation](https://rescript-lang.org/llms/react//llm-full.txt): The complete ReScript React documentation including all examples and additional content +- [ abridged documentation](https://rescript-lang.org/llms/react//llm-small.txt): A minimal ReScript React reference with the essential content ## Language Documentation -- [ReScript documentation](https://rescript-lang.org/llms/manual/llms.txt): This is the developer documentation for ReScript. +- [ReScript documentation](https://rescript-lang.org/llms.txt): This is the developer documentation for ReScript. ## Notes -- The abridged documentation excludes the detailed examples, and supplementary information +- The abridged documentation excludes the detailed examples and supplementary information - The complete documentation includes all content from the official documentation - Package-specific documentation files contain only the content relevant to that package -- The content is automatically generated from the same source as the official documentation for the specific version \ No newline at end of file +- The content is automatically generated from the same source as the official documentation for the specific version diff --git a/apps/docs/scripts/__tests__/generate-llms.test.mjs b/apps/docs/scripts/__tests__/generate-llms.test.mjs new file mode 100644 index 000000000..1d2caae9e --- /dev/null +++ b/apps/docs/scripts/__tests__/generate-llms.test.mjs @@ -0,0 +1,135 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import child_process from "node:child_process"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); +const docsRoot = path.resolve(__dirname, "../.."); +const generatorPath = path.join(docsRoot, "_scripts", "generate_llms.mjs"); + +let writeFile = (root, filePath, content) => { + let fullPath = path.join(root, filePath); + fs.mkdirSync(path.dirname(fullPath), { recursive: true }); + fs.writeFileSync(fullPath, content); +}; + +let makeWorkspace = () => { + let root = fs.mkdtempSync(path.join(os.tmpdir(), "generate llms-")); + + writeFile( + root, + "markdown-pages/docs/manual/introduction.mdx", + `--- +title: "Introduction" +--- + +# Manual Introduction + +\`\`\`res +let answer = 42 +\`\`\` +`, + ); + + writeFile( + root, + "markdown-pages/docs/react/introduction.mdx", + `--- +title: "React Introduction" +--- + +# React Introduction +`, + ); + + writeFile( + root, + "public/llms/manual/template.txt", + `# Manual LLMs + +Current version: + +- [Complete documentation](https://rescript-lang.org/llms/manual//llm-full.txt) +- [Abridged documentation](https://rescript-lang.org/llms/manual//llm-small.txt) +`, + ); + writeFile(root, "public/llms/manual/llms.txt", "stale manual index"); + + writeFile( + root, + "public/llms/manual/template.mdx", + `# Manual LLMs + +- [/llms/manual//llm-full.txt](/llms/manual//llm-full.txt) +- [/llms/manual//llm-small.txt](/llms/manual//llm-small.txt) +`, + ); + + writeFile( + root, + "public/llms/react/template.txt", + `# React LLMs + +Current version: + +- [Complete documentation](https://rescript-lang.org/llms/react//llm-full.txt) +- [Abridged documentation](https://rescript-lang.org/llms/react//llm-small.txt) +`, + ); + + writeFile( + root, + "public/llms/react/template.mdx", + `# React LLMs + +- [/llms/react//llm-full.txt](/llms/react//llm-full.txt) +- [/llms/react//llm-small.txt](/llms/react//llm-small.txt) +`, + ); + + return root; +}; + +let readFile = (root, filePath) => + fs.readFileSync(path.join(root, filePath), "utf8"); + +test("generate_llms writes the default manual index at the site root", () => { + let root = makeWorkspace(); + + child_process.execFileSync(process.execPath, [generatorPath], { + cwd: root, + stdio: "pipe", + }); + + let currentLlms = readFile(root, "public/llms.txt"); + let versionedLlms = readFile(root, "public/llms/manual/v12/llms.txt"); + + assert.doesNotMatch(currentLlms, //); + assert.match(currentLlms, /Current version: v12/); + assert.match( + currentLlms, + /https:\/\/rescript-lang\.org\/llms\/manual\/v12\/llm-full\.txt/, + ); + assert.match( + currentLlms, + /https:\/\/rescript-lang\.org\/llms\/manual\/v12\/llm-small\.txt/, + ); + + assert.equal( + fs.existsSync(path.join(root, "public/llms/manual/llms.txt")), + false, + ); + assert.equal(versionedLlms, currentLlms); + assert.equal( + readFile(root, "public/llms/manual/v12/llm-full.txt"), + readFile(root, "public/llms/manual/llm-full.txt"), + ); + assert.equal( + readFile(root, "public/llms/manual/v12/llm-small.txt"), + readFile(root, "public/llms/manual/llm-small.txt"), + ); +}); diff --git a/apps/docs/scripts/generate_llms.res b/apps/docs/scripts/generate_llms.res index 43a648872..e319951ad 100644 --- a/apps/docs/scripts/generate_llms.res +++ b/apps/docs/scripts/generate_llms.res @@ -22,6 +22,20 @@ let clearFile = (filePath: string): unit => { Node.Fs.writeFileSync(filePath, "") } +let removeFileIfExists = (filePath: string): unit => { + if Node.Fs.existsSync(filePath) { + Node.Fs.unlinkSync(filePath) + } +} + +let writeTextFile = (filePath: string, content: string): unit => { + Node.Fs.writeFileSync(filePath, content, ~encoding="utf8") +} + +let copyFile = (sourcePath: string, targetPath: string): unit => { + writeTextFile(targetPath, readMarkdownFile(sourcePath)) +} + let createDirectoryIfNotExists = (dirPath: string): unit => { if !Node.Fs.existsSync(dirPath) { Node.Fs.mkdirSync(dirPath) @@ -68,21 +82,56 @@ let createSmallFile = (content: string, filePath: string): unit => { Node.Fs.appendFileSync(filePath, smallContent, "utf8") } -// TODO: post RR7 - refactor to remove the version parameter, as it's unused -let createLlmsFiles = (_version: string, docsDirectory: string, llmsDirectory: string): unit => { +let replaceVersionPlaceholder = (content: string, version: string): string => { + let regex = RegExp.fromString("", ~flags="g") + String.replaceRegExp(content, regex, version) +} + +let createLlmsFiles = ( + ~version: string, + ~txtFilePath: string, + docsDirectory: string, + llmsDirectory: string, +): unit => { let mdxFileTemplatePath = llmsDirectory->Node.Path.join2("template.mdx") let mdxFilePath = docsDirectory->Node.Path.join2("llms.mdx") let txtFileTemplatePath = llmsDirectory->Node.Path.join2("template.txt") - let txtFilePath = llmsDirectory->Node.Path.join2("llms.txt") Console.log(txtFilePath) - Node.Fs.writeFileSync(mdxFilePath, readMarkdownFile(mdxFileTemplatePath)) + writeTextFile( + mdxFilePath, + readMarkdownFile(mdxFileTemplatePath)->replaceVersionPlaceholder(version), + ) + + writeTextFile( + txtFilePath, + readMarkdownFile(txtFileTemplatePath)->replaceVersionPlaceholder(version), + ) +} - Node.Fs.writeFileSync(txtFilePath, readMarkdownFile(txtFileTemplatePath)) +let copyCurrentFilesToVersion = ( + ~version: string, + ~llmsDirectory: string, + ~fullFilePath: string, + ~smallFilePath: string, + ~txtFilePath: string, +): unit => { + let versionedLlmsDirectory = llmsDirectory->Node.Path.join2(version) + + createDirectoryIfNotExists(versionedLlmsDirectory) + copyFile(txtFilePath, versionedLlmsDirectory->Node.Path.join2("llms.txt")) + copyFile(fullFilePath, versionedLlmsDirectory->Node.Path.join2("llm-full.txt")) + copyFile(smallFilePath, versionedLlmsDirectory->Node.Path.join2("llm-small.txt")) } -let generateFile = (docsDirectory: string, llmsDirectory: string): unit => { +let generateFile = ( + ~currentVersion: string, + ~txtFilePath: string, + ~staleTxtFilePath: option=?, + docsDirectory: string, + llmsDirectory: string, +): unit => { let fullFileName = "llm-full.txt" let smallFileName = "llm-small.txt" @@ -94,7 +143,12 @@ let generateFile = (docsDirectory: string, llmsDirectory: string): unit => { clearFile(fullFilePath) clearFile(smallFilePath) - createLlmsFiles("", docsDirectory, llmsDirectory) + switch staleTxtFilePath { + | Some(filePath) => removeFileIfExists(filePath) + | None => () + } + + createLlmsFiles(~version=currentVersion, ~txtFilePath, docsDirectory, llmsDirectory) docsDirectory ->collectFiles @@ -107,13 +161,35 @@ let generateFile = (docsDirectory: string, llmsDirectory: string): unit => { content->createSmallFile(smallFilePath) } }) + + copyCurrentFilesToVersion( + ~version=currentVersion, + ~llmsDirectory, + ~fullFilePath, + ~smallFilePath, + ~txtFilePath, + ) } +let currentManualVersion = "v12" +let currentReactVersion = "latest" + let manualDocsDirectory = "markdown-pages/docs/manual" let reactDocsDirectory = "markdown-pages/docs/react" let manualLlmsDirectory = "public/llms/manual" let reactLlmsDirectory = "public/llms/react" -generateFile(manualDocsDirectory, manualLlmsDirectory) -generateFile(reactDocsDirectory, reactLlmsDirectory) +generateFile( + ~currentVersion=currentManualVersion, + ~txtFilePath="public/llms.txt", + ~staleTxtFilePath="public/llms/manual/llms.txt", + manualDocsDirectory, + manualLlmsDirectory, +) +generateFile( + ~currentVersion=currentReactVersion, + ~txtFilePath=reactLlmsDirectory->Node.Path.join2("llms.txt"), + reactDocsDirectory, + reactLlmsDirectory, +) diff --git a/apps/docs/src/bindings/Node.res b/apps/docs/src/bindings/Node.res index 9c4f63af3..cc49181dd 100644 --- a/apps/docs/src/bindings/Node.res +++ b/apps/docs/src/bindings/Node.res @@ -32,6 +32,7 @@ module Fs = { @module("fs") external appendFileSync: (string, string, string) => unit = "appendFileSync" @module("fs") external existsSync: string => bool = "existsSync" @module("fs") external mkdirSync: string => unit = "mkdirSync" + @module("fs") external unlinkSync: string => unit = "unlinkSync" @module("fs") external statSync: string => {.."isDirectory": unit => bool} = "statSync" @module("node:fs/promises") external readFile: (string, string) => promise = "readFile" } From 4d5e2af04967f3a685d5a9333402b3c48e25e169 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Thu, 7 May 2026 10:47:40 -0400 Subject: [PATCH 2/9] more tweaks --- apps/docs/markdown-pages/docs/react/llms.mdx | 12 ++-- apps/docs/public/llms/react/template.mdx | 6 +- apps/docs/public/llms/react/template.txt | 70 ++++++++++++++++++- .../scripts/__tests__/generate-llms.test.mjs | 37 ++++++++++ apps/docs/scripts/generate_llms.res | 15 +++- 5 files changed, 127 insertions(+), 13 deletions(-) diff --git a/apps/docs/markdown-pages/docs/react/llms.mdx b/apps/docs/markdown-pages/docs/react/llms.mdx index 2b701055a..f1910211b 100644 --- a/apps/docs/markdown-pages/docs/react/llms.mdx +++ b/apps/docs/markdown-pages/docs/react/llms.mdx @@ -9,9 +9,9 @@ section: "Overview" We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications. -Current ReScript React documentation channel: `latest`. +Current ReScript React documentation version: `v0.14.2`. -The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the named files under `/llms/react/latest/` when you want an explicit path for the docs channel generated by this build. +The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the versioned files under `/llms/react/v0.14.2/` when you want a stable path for this ReScript React documentation version. ## Default Current Files @@ -19,11 +19,11 @@ The unversioned files under `/llms/react/` are the default entry points and alwa - [/llms/react/llm-full.txt](/llms/react/llm-full.txt) - complete current documentation for ReScript React. - [/llms/react/llm-small.txt](/llms/react/llm-small.txt) - abridged current documentation without detailed examples. -## Named Files +## Versioned Files -- [/llms/react/latest/llms.txt](/llms/react/latest/llms.txt) - a list of the available files for ReScript React `latest`. -- [/llms/react/latest/llm-full.txt](/llms/react/latest/llm-full.txt) - complete documentation for ReScript React `latest`. -- [/llms/react/latest/llm-small.txt](/llms/react/latest/llm-small.txt) - abridged documentation for ReScript React `latest`. +- [/llms/react/v0.14.2/llms.txt](/llms/react/v0.14.2/llms.txt) - a list of the available files for ReScript React `v0.14.2`. +- [/llms/react/v0.14.2/llm-full.txt](/llms/react/v0.14.2/llm-full.txt) - complete documentation for ReScript React `v0.14.2`. +- [/llms/react/v0.14.2/llm-small.txt](/llms/react/v0.14.2/llm-small.txt) - abridged documentation for ReScript React `v0.14.2`. ## Language Documentation diff --git a/apps/docs/public/llms/react/template.mdx b/apps/docs/public/llms/react/template.mdx index 5783e83a1..943c38b75 100644 --- a/apps/docs/public/llms/react/template.mdx +++ b/apps/docs/public/llms/react/template.mdx @@ -9,9 +9,9 @@ section: "Overview" We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications. -Current ReScript React documentation channel: ``. +Current ReScript React documentation version: ``. -The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the named files under `/llms/react//` when you want an explicit path for the docs channel generated by this build. +The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the versioned files under `/llms/react//` when you want a stable path for this ReScript React documentation version. ## Default Current Files @@ -19,7 +19,7 @@ The unversioned files under `/llms/react/` are the default entry points and alwa - [/llms/react/llm-full.txt](/llms/react/llm-full.txt) - complete current documentation for ReScript React. - [/llms/react/llm-small.txt](/llms/react/llm-small.txt) - abridged current documentation without detailed examples. -## Named Files +## Versioned Files - [/llms/react//llms.txt](/llms/react//llms.txt) - a list of the available files for ReScript React ``. - [/llms/react//llm-full.txt](/llms/react//llm-full.txt) - complete documentation for ReScript React ``. diff --git a/apps/docs/public/llms/react/template.txt b/apps/docs/public/llms/react/template.txt index 39da43f9a..145a79745 100644 --- a/apps/docs/public/llms/react/template.txt +++ b/apps/docs/public/llms/react/template.txt @@ -4,9 +4,9 @@ ## ReScript React Documentation -Current ReScript React documentation channel: . +Current ReScript React documentation version: . -The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the named files under `/llms/react//` when you want an explicit path for the docs channel generated by this build. +The unversioned files under `/llms/react/` are the default entry points and always describe the current ReScript React docs. Use the versioned files under `/llms/react//` when you want a stable path for this ReScript React documentation version. ### Default Current Files @@ -14,7 +14,7 @@ The unversioned files under `/llms/react/` are the default entry points and alwa - [Complete current documentation](https://rescript-lang.org/llms/react/llm-full.txt): The complete current ReScript React documentation including all examples and additional content - [Abridged current documentation](https://rescript-lang.org/llms/react/llm-small.txt): A minimal current version of the ReScript React documentation, with the essential content for quick reference -### Named Files +### Versioned Files - [ LLMs index](https://rescript-lang.org/llms/react//llms.txt): This file for ReScript React - [ complete documentation](https://rescript-lang.org/llms/react//llm-full.txt): The complete ReScript React documentation including all examples and additional content @@ -24,6 +24,70 @@ The unversioned files under `/llms/react/` are the default entry points and alwa - [ReScript documentation](https://rescript-lang.org/llms.txt): This is the developer documentation for ReScript. +## General Guidelines for Agents + +### Coding best practices + +- Prefer small functions with a single purpose. +- Use a functional style, but keep code straightforward and readable. +- Keep files and modules focused. +- Use the pipe-first operator (`->`) for chaining. +- Resolve warnings rather than working around them. +- Do not add type annotations unless they are needed for clarity or to resolve an error. ReScript's type inference is strong. + +### ReScript rules + +- Target ReScript v12 syntax and APIs. +- Do not use the legacy `Belt` or `Js` modules. Use the modern standard library and core modules instead. +- Use the `JSON.t` type for JSON values. +- Prefer `async` and `await` when working with promises. +- Do not use `@genType`. +- Do not use `%raw` unless explicitly asked or there is no clean binding-based alternative. +- Do not use `Object.magic`. +- `.res` files should be PascalCase to match ReScript module conventions. +- Never edit generated `.jsx` or `.mjs` files directly. Edit the corresponding `.res` source and regenerate. + +### ReScript v12 syntax traps + +- Do not use a `return` keyword. Pattern-match arms must be expressions, not statements. + - Wrong: `| Some(_) => return Error(InvalidCompleted)` + - Right: `| Some(_) => Error(InvalidCompleted)` +- Do not use inline record types in function signatures. Declare the type first. + - Wrong: `let f = (j: Result.t<{title: string}, e>) => ...` + - Right: `type parsed = {title: string}; let f = (j: Result.t) => ...` +- The JSON boolean variant is `JSON.Boolean`, not `JSON.Bool`. +- Use `JSON.parseOrThrow`, not deprecated `JSON.parseExn`. +- Single-field record values need the field name: `{status: status}`, not `{status}`. +- `Int.fromString` takes 2 arguments in v12: `Int.fromString(~radix=10, s)`. Wrap it as `s => Int.fromString(~radix=10, s)` when passing it as a callback. + +### ReScript React rules + +- Use ReScript JSX v4 syntax. +- `React.useState` takes an initializer function: `let (age, setAge) = React.useState(_ => 4)`. +- Every expression inside an interpolated string must be a `string`. + - Wrong: `` `age = ${42}` `` + - Right: `` `age = ${42->Int.toString}` `` +- `type` is a ReScript keyword. Use `type_` for JSX props: `