# rescript-lang.org: Official ReScript Documentation Site

> rescript-lang.org is the official documentation platform for ReScript, built as a pre-rendered site with MDX, React Router, Vite, Cloudflare Pages, and validation for documentation examples. It is mainly for ReScript documentation contributors and maintainers, not applications seeking a general-purpose static site generator.

**rescript-lang/rescript-lang.org** — Official documentation website for the ReScript programming language

- Repository: https://github.com/rescript-lang/rescript-lang.org
- Website: https://rescript-lang.org
- Stars: 1,853 · Forks: 261
- Language: MDX
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/rescript-lang-rescript-lang-org

## What rescript-lang.org Owns

This repository solves a narrower problem than building an arbitrary documentation site: it is the source for the official ReScript language documentation published at `https://rescript-lang.org`. The intended contributors are people who need to correct language material, add API or syntax documentation, maintain the site interface, or operate its documentation build. The repository itself directs technical issues with the ReScript language to the separate compiler repository.

The site is a fully pre-rendered static application. Its documentation content is written primarily in MDX, while the application uses ReScript, React 19, React Router, Vite, and Tailwind CSS. Cloudflare Pages is the stated deployment target. This combination makes the output suitable for a documentation site that needs concrete routes and generated HTML, while also creating a repository-specific build process rather than a simple collection of Markdown files.

The project also owns more than article text. According to the README, it generates a sitemap from prerendered HTML, structures headings for Algolia DocSearch, validates relative links and redirects, compiles documentation examples, and checks route types. Consequently, a contribution can affect compiler examples, search metadata, generated ReScript code, navigation, or deployment behavior. A pull request that edits only prose may still need to satisfy checks outside the visible page.

## Content, Routes, and Generated Types

The content and application layers meet through a shared route configuration. The README identifies the documentation route table as `apps/docs/route-config.mjs`. React Router and `apps/docs/generate-route-types.mjs` read that same configuration, which includes MDX pages and API modules. The generated result is `packages/shared/src/Path.res`, used by ReScript code that needs consistent route knowledge.

This is an important maintenance boundary. After changing routes, adding or removing MDX pages, or updating API data during a watch session, the documented instruction is to regenerate the shared route type. CI rejects a stale generated file, so leaving the generated ReScript file unchanged is not harmless. Route work therefore spans at least a JavaScript configuration file, content or API metadata, and a generated ReScript file.

The repository structure also separates responsibilities. `src/` contains shared ReScript bindings, logic, components, and layouts, while `markdown-pages/` holds MDX documentation, blog, community, and syntax lookup content. The top-level repository also contains `apps/`, `packages/`, `data/`, `styles/`, `scripts/`, `plugins/`, `compilers/`, and `__tests__/`. The README specifically notes that Tailwind configuration lives in `styles/main.css`; there is no `tailwind.config.js`. Contributors should therefore verify the actual route paths in the repository rather than assuming the abbreviated README structure is the complete workspace layout.

## Running the ReScript Documentation Locally

The README requires `node@26` or higher and specifies `yarn@4.13.0` through Corepack. Install Corepack globally, enable it, install dependencies, and start the development environment with these commands:

```sh
npm install --global corepack
corepack enable
yarn install
yarn dev
```

The final command prepares generated assets, starts the ReScript watcher, runs the React Router and Vite development server, and serves the built client through Wrangler Pages. This is a real local workflow rather than a static Markdown preview. The reader should expect several coordinated processes, so `node@26`, the Corepack-managed Yarn version, installed dependencies, and generated files all matter.

Search is enabled through public Algolia DocSearch runtime variables. For a development environment that needs search, the README names these exact variables:

```sh
VITE_ALGOLIA_APP_ID="..."
VITE_ALGOLIA_INDEX_NAME="..."
VITE_ALGOLIA_SEARCH_API_KEY="..."
```

The site never uploads records or replaces indexes during a build. An Algolia crawler owns indexing and index settings, while the frontend uses public runtime credentials. The GitHub deploy workflow passes public GitHub secrets with the same names to the `yarn build` step. Build and deployment configuration should not include an Algolia admin or write key. `VITE_ALGOLIA_INDEX_NAME` is the complete runtime index name, with no automatically added `prod_` or `dev_` prefix.

The generated `sitemap.xml`, `DocSearch-content` wrappers, hidden section markers such as `Manual` and `API`, and unique heading `id` attributes form part of the crawler contract. Search configuration therefore cannot be evaluated only by checking whether a search box appears in the interface.

## Validation of ReScript Examples and Site Changes

The repository treats documentation code as testable output. `yarn test` runs example compilation in the manual, React documentation, guides, and syntax lookup. It compares displayed JavaScript and JSX output with the installed compiler. The same command validates relative Markdown links under `markdown-pages/` and checks redirect rules.

This catches a failure mode that ordinary prose review misses: an example may remain readable while producing output that no longer agrees with the compiler currently used by the site. The supported fence conventions include `res`, `rescript`, `res sig`, `resi`, `res prelude`, and file-specific blocks such as `res file=MathUtils.res` and `resi file=MathUtils.resi`. Indented fences are supported. The README also documents `res nocheck` for examples that are intentionally invalid, which shows that compilation validation has an explicit escape hatch and should be used selectively.

Route changes have a separate stale-file gate. The following command checks that the generated shared route type matches current routes:

```sh
yarn check:routes
```

Vitest browser tests provide another layer. They use Vitest in browser mode with Playwright, with test files in `__tests__/` written in ReScript. The documented headless command is:

```sh
yarn ci:test
```

For watch mode, the README documents `yarn vitest`. Screenshot baselines can be updated with `yarn vitest:update`, but the instruction is to update only screenshots affected intentionally. This distinction matters because accepting unrelated baseline changes can conceal visual regressions. The repository also provides `yarn format`, which runs Prettier and the ReScript formatter, and `yarn build`, which executes the full production build.

## Search and Cloudflare Pages Constraints

Algolia DocSearch is decoupled from the site build. The frontend needs only the public app ID, index name, and search API key. Crawl quality depends on rendered HTML rather than repository build scripts uploading documents. Searchable bodies must use `DocSearch-content`; crawlable sections need hidden `DocSearch-lvl0` markers; and headings need unique `id` attributes for section links.

The documented crawler selectors map levels zero through six to section markers and headings. Content selectors cover paragraphs and list items within `.DocSearch-content`. Production start URLs, ranking, and crawl schedules remain in the Algolia dashboard. That division is useful for security because deployments do not need Algolia write credentials, but it also means a successful local build does not confirm that search records were refreshed. Search content availability depends on a separate crawler operation after deployment.

Cloudflare Pages serves the generated site, while `functions/` exists for Cloudflare Pages Functions. The README calls the application fully pre-rendered, so contributors should not assume every interaction requires a live application server. At the same time, Wrangler Pages participates in the local `yarn dev` workflow. This setup is appropriate for a public documentation deployment, though it offers little value to someone who only wants a generic React site without project-specific MDX, route generation, compiler-example validation, or DocSearch integration.

## Maintenance Signals and Upgrade Work

The repository is not archived, and the last push was on 2026-10-14. There are no GitHub releases, so there is no release cadence documented through GitHub Releases. Maintenance work is represented through source changes and build automation rather than versioned site packages. The MIT license permits reuse and modification under its terms, although license interpretation for a particular deployment remains a matter for the relevant counsel.

Upgrade effort depends on the layer being changed. Dependency and framework updates pass through a Yarn workspace whose root package is marked private and uses Yarn 4. Toolchain changes must preserve `node@26`, Corepack, the ReScript compiler workflow, React Router route generation, Vite, Tailwind v4, Cloudflare Pages, and the test commands. Content changes may require example compilation, link validation, route regeneration, screenshot review, or DocSearch marker checks. Route changes have an explicit CI failure mode when generated types are stale.

The repository includes bundled compiler versions under `compilers/` for playground and example validation, so compiler behavior is part of the documentation toolchain rather than an incidental dependency. This helps keep examples tied to a defined site environment, but it also creates another artifact to track when compiler changes land. Documentation contributors should inspect `yarn build`, `yarn test`, `yarn ci:test`, and the route-generation workflow before assuming that a local text edit has covered all affected checks.

## Conclusion

Adopt this repository if you need to build, validate, search, or deploy the official ReScript documentation. Do not choose it merely as a general website framework, because its scripts, routes, MDX conventions, generated ReScript types, and Algolia crawler contract are tied to this documentation platform. Before changing it, verify the installed `node@26` requirement, inspect `apps/docs/route-config.mjs`, and account for route regeneration, documentation tests, public Algolia variables, and the Cloudflare Pages deployment model.

## FAQ

### How do I install and run rescript-lang.org locally?

Use `node@26` or higher, install and enable Corepack, then run `yarn install` and `yarn dev`. The README states that the project uses `yarn@4.13.0` through Corepack.

### How does rescript-lang.org integrate Algolia DocSearch?

The frontend uses `VITE_ALGOLIA_APP_ID`, `VITE_ALGOLIA_INDEX_NAME`, and `VITE_ALGOLIA_SEARCH_API_KEY`. The DocSearch crawler controls indexing and settings, while site builds do not upload records or use an Algolia admin or write key.

### When should I run `yarn build:routes` in rescript-lang.org?

Run it after changing routes, adding or removing MDX pages, or updating API data during a watch session. The generated route type lives at `packages/shared/src/Path.res`, and CI rejects a stale generated file.

### What does `yarn test` validate in rescript-lang.org?

It compiles selected ReScript documentation examples and compares their shown JavaScript and JSX output with the installed compiler. It also validates relative Markdown links under `markdown-pages/` and redirect rules.

## Sources

- [Issues](https://github.com/rescript-lang/rescript-lang.org/issues)
- [License: MIT](https://github.com/rescript-lang/rescript-lang.org/blob/master/LICENSE)
- [Project website](https://rescript-lang.org)
- [README](https://github.com/rescript-lang/rescript-lang.org/blob/master/README.md)
- [rescript-lang/rescript-lang.org on GitHub](https://github.com/rescript-lang/rescript-lang.org)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rescript-lang-rescript-lang-org