diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 53569b3ef..54da80e6e 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -41,9 +41,7 @@ jobs: if [[ "$RAW_BRANCH" == "master" ]]; then echo "VITE_DEPLOYMENT_URL=" >> "$GITHUB_ENV" else - SAFE_BRANCH="${RAW_BRANCH//\//-}" - - SAFE_BRANCH=$(echo "$SAFE_BRANCH" | tr '[:upper:]' '[:lower:]') + SAFE_BRANCH=$(echo "$RAW_BRANCH" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]+/-/g; s/^-+//; s/-+$//; s/-+/-/g') SAFE_BRANCH="${SAFE_BRANCH:0:28}" echo "SAFE_BRANCH=$SAFE_BRANCH" >> "$GITHUB_ENV" @@ -109,9 +107,7 @@ jobs: if [[ "$RAW_BRANCH" == "master" ]]; then CYPRESS_BASE_URL="https://rescript-lang.org" else - SAFE_BRANCH="${RAW_BRANCH//\//-}" - - SAFE_BRANCH=$(echo "$SAFE_BRANCH" | tr '[:upper:]' '[:lower:]') + SAFE_BRANCH=$(echo "$RAW_BRANCH" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]+/-/g; s/^-+//; s/-+$//; s/-+/-/g') SAFE_BRANCH="${SAFE_BRANCH:0:28}" CYPRESS_BASE_URL="https://${SAFE_BRANCH}.rescript-lang.pages.dev" 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/__tests__/MarkdownComponents_.test.res b/apps/docs/__tests__/MarkdownComponents_.test.res index 9df5204e1..8cd859217 100644 --- a/apps/docs/__tests__/MarkdownComponents_.test.res +++ b/apps/docs/__tests__/MarkdownComponents_.test.res @@ -360,11 +360,7 @@ test("renders Image with small size", async () => { let screen = await render(
- +
, ) @@ -372,6 +368,7 @@ test("renders Image with small size", async () => { await element(caption)->toBeVisible let wrapper = await screen->getByTestId("image-small-wrapper") + await waitForImages("[data-testid='image-small-wrapper']") await element(wrapper)->toMatchScreenshot("markdown-image-small") }) diff --git a/apps/docs/markdown-pages/docs/manual/llms.mdx b/apps/docs/markdown-pages/docs/manual/llms.mdx index 7e73b6153..df59645c2 100644 --- a/apps/docs/markdown-pages/docs/manual/llms.mdx +++ b/apps/docs/markdown-pages/docs/manual/llms.mdx @@ -10,16 +10,29 @@ 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... +This ReScript manual major version: `v12 (current 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 files under `/llms/manual/v13/` (pre-release version) or `/llms/manual/v12/` (current version) when you want an explicit major-version path. These major-version paths use the latest generated documentation for that major version and avoid full patch numbers in the URL. -...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. + +## 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. + +## Major Version Files + +- [v13 pre-release LLMs index](/llms/manual/v13/llms.txt) - a list of the available files for the latest ReScript v13 pre-release documentation. +- [v13 pre-release complete documentation](/llms/manual/v13/llm-full.txt) - complete latest ReScript v13 pre-release documentation. +- [v13 pre-release abridged documentation](/llms/manual/v13/llm-small.txt) - abridged latest ReScript v13 pre-release documentation. +- [v12 current LLMs index](/llms/manual/v12/llms.txt) - a list of the available files for the current ReScript v12 documentation. +- [v12 current complete documentation](/llms/manual/v12/llm-full.txt) - complete current ReScript v12 documentation. +- [v12 current abridged documentation](/llms/manual/v12/llm-small.txt) - abridged current ReScript v12 documentation. diff --git a/apps/docs/markdown-pages/docs/react/llms.mdx b/apps/docs/markdown-pages/docs/react/llms.mdx index de3672cd5..1183e93b3 100644 --- a/apps/docs/markdown-pages/docs/react/llms.mdx +++ b/apps/docs/markdown-pages/docs/react/llms.mdx @@ -9,16 +9,28 @@ 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 version: `v0.14.2`. +ReScript React package version: `v0.14.2`. +React version: `v19.2.4`. -- [/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 versioned files under `/llms/react/v0.14.2/` when you want a stable path for this ReScript React documentation version. -...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. + +## Versioned Files + +- [/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 + +- [/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/_redirects b/apps/docs/public/_redirects index f12879a3d..775be8113 100644 --- a/apps/docs/public/_redirects +++ b/apps/docs/public/_redirects @@ -5,6 +5,9 @@ /docs/manual/next/* /docs/manual/:splat 308 /docs/react/latest/* /docs/react/:splat 308 +/llms/manual/llms.txt /llms.txt 307 +/llms/manual/latest/llms.txt /llms.txt 307 +/llms/manual/next/llms.txt /llms.txt 307 /llms/manual/latest/* /llms/manual/:splat 307 /llms/manual/next/* /llms/manual/:splat 307 @@ -13,4 +16,4 @@ /docs/manual/v9.0.0/* https://v11.rescript-lang.org/docs/manual/v9.0.0/:splat 308 /docs/manual/v8.0.0/* https://v11.rescript-lang.org/docs/manual/v8.0.0/:splat 308 /docs/react/v0.11.0/* https://v11.rescript-lang.org/docs/react/v0.11.0/:splat 308 -/docs/react/v0.10.0/* https://v11.rescript-lang.org/docs/react/v0.10.0/:splat 308 \ No newline at end of file +/docs/react/v0.10.0/* https://v11.rescript-lang.org/docs/react/v0.10.0/:splat 308 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..389404f95 100644 --- a/apps/docs/public/llms/manual/template.mdx +++ b/apps/docs/public/llms/manual/template.mdx @@ -10,16 +10,29 @@ 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... +This ReScript manual major 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 files under `/llms/manual/v13/` (pre-release version) or `/llms/manual/v12/` (current version) when you want an explicit major-version path. These major-version paths use the latest generated documentation for that major version and avoid full patch numbers in the URL. -...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. + +## 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. + +## Major Version Files + +- [v13 pre-release LLMs index](/llms/manual/v13/llms.txt) - a list of the available files for the latest ReScript v13 pre-release documentation. +- [v13 pre-release complete documentation](/llms/manual/v13/llm-full.txt) - complete latest ReScript v13 pre-release documentation. +- [v13 pre-release abridged documentation](/llms/manual/v13/llm-small.txt) - abridged latest ReScript v13 pre-release documentation. +- [v12 current LLMs index](/llms/manual/v12/llms.txt) - a list of the available files for the current ReScript v12 documentation. +- [v12 current complete documentation](/llms/manual/v12/llm-full.txt) - complete current ReScript v12 documentation. +- [v12 current abridged documentation](/llms/manual/v12/llm-small.txt) - abridged current ReScript v12 documentation. diff --git a/apps/docs/public/llms/manual/template.txt b/apps/docs/public/llms/manual/template.txt index 9d4b3ba71..c6b24ac7f 100644 --- a/apps/docs/public/llms/manual/template.txt +++ b/apps/docs/public/llms/manual/template.txt @@ -4,8 +4,15 @@ ## 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 +This ReScript manual major version: . + +The root `/llms.txt` file is the default entry point and always describes the current stable manual. Use the files under `/llms/manual/v13/` (pre-release version) or `/llms/manual/v12/` (current version) when you want an explicit major-version path. These major-version paths use the latest generated documentation for that major version and avoid full patch numbers in the URL. + +### 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 ## Individual Package Documentation @@ -13,7 +20,11 @@ ## 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 + +### Major Version Files + + diff --git a/apps/docs/public/llms/react/template.mdx b/apps/docs/public/llms/react/template.mdx index de3672cd5..ba61e3f05 100644 --- a/apps/docs/public/llms/react/template.mdx +++ b/apps/docs/public/llms/react/template.mdx @@ -9,16 +9,28 @@ 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 version: ``. +ReScript React package version: ``. +React version: ``. -- [/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 versioned files under `/llms/react//` when you want a stable path for this ReScript React documentation version. -...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. + +## 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 ``. +- [/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..8da45a75d 100644 --- a/apps/docs/public/llms/react/template.txt +++ b/apps/docs/public/llms/react/template.txt @@ -4,16 +4,95 @@ ## 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 version: . +ReScript React package version: . +React version: . + +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 + +- [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 + +### 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 +- [ 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. + +## 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: `