Skip to content

Commit f614a77

Browse files
jderochervlkjderochervlk
authored
docs: update README for new project structure and workflows (#1266)
Streamline project overview, clarify directory layout, update setup and testing instructions, and remove outdated Next.js references. Add details for contributing, blog posts, and company logos.
1 parent 91c9add commit f614a77

1 file changed

Lines changed: 73 additions & 107 deletions

File tree

‎README.md‎

Lines changed: 73 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -4,165 +4,131 @@
44

55
This is the official documentation platform for the [ReScript](https://rescript-lang.org) programming language.
66

7+
The site is a fully pre-rendered static app built with ReScript, React 19, React Router, Vite, and Tailwind CSS, and deployed to Cloudflare Pages.
8+
9+
Route modules live in `app/routes/`, shared ReScript UI code lives in `src/`, and MDX content lives in `markdown-pages/`.
10+
711
**Please report any technical issues with ReScript to the [compiler repository](https://github.com/rescript-lang/rescript).**
812

9-
**In case you are missing some specific documentation:**
13+
**If you are missing specific documentation:**
1014

11-
- Some language / compiler feature may not be documented yet
12-
- Create an issue to let us know what you are missing
13-
- In case you want to contribute missing docs, please refer to our [Contribution section](#contributing)
15+
- Some language or compiler features may not be documented yet.
16+
- Open an issue to let us know what is missing.
17+
- If you want to contribute missing docs, see [Contributing](#contributing).
1418

1519
## System Requirements
1620

1721
- `node@22` or higher
18-
- `yarn` or `corepack`
22+
- `corepack` enabled
23+
24+
This repository uses `yarn@4.13.0` via Corepack.
1925

2026
## Setup
2127

2228
```sh
23-
# For first time clone / build (install dependencies)
24-
yarn
25-
26-
# Run ReScript, Vite, and Wrangler in development mode
29+
corepack enable
30+
yarn install
2731
yarn dev
2832
```
2933

30-
## Project Structure Overview
31-
32-
- `data`: Contains hand-curated data, such as sidebar ordering, blog data, etc
33-
- `index_data`: Contains generated data, usually generated by scripts like `scripts/extract-tocs.js`
34-
- `compilers`: Contains a subdirectory with independently installed ReScript compilers, to be able to compile / test examples with different ReScript versions
35-
- `misc_docs`: Contains `pages` independent resources that are embedded in miscellaneous pages (e.g. for the syntax lookup)
36-
- `pages`: All Next pages. Those are written in JS / MDX, some pages are re-exporting ReScript based pages from the `src/` directory.
37-
- `styles`: Contains all extra CSS that cannot be expressed with Tailwind
38-
- `src`: Contains all ReScript related code for the UI. Within `src`, you will also find all ReScript based Next pages that are re-exported in the `pages` directory
39-
- `/bindings`: (Zero-cost) bindings to JS libraries / apis
40-
- `/common`: ReScript modules that are neither `bindings`, nor `components`
41-
- `/components`: ReScript / React components used by multiple pages
42-
- `/ffi`: (to be deprecated) Plain JS that some ReScript code binds to (use `raw` statements for that)
43-
- `/layouts`: All Next layouts used in our pages. Check out `src/common/App.res` for mapping layouts to routes
44-
- `plugins`: Contains plugins for all kinds of things: HighlightJS, MDX, webpack loader, etc.
45-
- `scripts`: Contains a mix of JS / ReScript based scripts that do all kind of code generation / code introspection logic
46-
- `tailwind.config.js`: Contains our Tailwind configuration for all the low level design tokens
34+
`yarn dev` prepares generated assets, starts the ReScript watcher, runs the React Router/Vite dev server, and serves the built client through Wrangler Pages.
4735

48-
## Run Tests
49-
50-
### Unit Tests (Vitest)
36+
## Project Structure Overview
5137

52-
We use [Vitest](https://vitest.dev/) with browser mode (Playwright) for component-level unit tests. Test files live in `__tests__/` and are written in ReScript.
38+
- `app/`: React Router app shell, layouts, route definitions, and route modules
39+
- `src/`: ReScript source code for bindings, shared logic, components, and layouts
40+
- `markdown-pages/`: MDX content for docs, blog, community pages, and syntax lookup
41+
- `data/`: Hand-curated data such as sidebar ordering and content metadata
42+
- `scripts/`: Build, code generation, and validation scripts
43+
- `functions/`: Cloudflare Pages Functions
44+
- `styles/`: Tailwind v4 theme and custom CSS
45+
- `public/`: Static assets such as images, fonts, and favicons
46+
- `plugins/`: HighlightJS, CodeMirror, and other content/build plugins
47+
- `compilers/`: Bundled ReScript compiler versions for playground and example validation
48+
- `__tests__/`: Vitest browser tests written in ReScript
49+
50+
Tailwind is configured in [`styles/main.css`](styles/main.css). There is no `tailwind.config.js`.
51+
52+
## Common Commands
53+
54+
| Command | Purpose |
55+
| -------------------- | ----------------------------------------------------------------- |
56+
| `yarn dev` | Prepare generated files and run the local development environment |
57+
| `yarn build` | Run the full production build |
58+
| `yarn preview` | Build and serve the generated static client locally |
59+
| `yarn build:res` | Compile ReScript only |
60+
| `yarn dev:res` | Run the ReScript compiler in watch mode |
61+
| `yarn format` | Run Prettier and the ReScript formatter |
62+
| `yarn test` | Run markdown example and href validation |
63+
| `yarn ci:test` | Run Vitest browser tests headlessly |
64+
| `yarn vitest` | Run Vitest directly |
65+
| `yarn vitest:update` | Update screenshot baselines headlessly |
66+
67+
## Testing
68+
69+
### Vitest Browser Tests
70+
71+
We use [Vitest](https://vitest.dev/) in browser mode with Playwright for component-level tests. Test files live in `__tests__/` and are written in ReScript.
5372

5473
```sh
55-
# Run tests in watch mode (headed browser)
74+
# Watch mode
5675
yarn vitest
5776

58-
# Run tests once in headless mode (same as CI)
77+
# Headless run (same mode used in CI)
5978
yarn ci:test
6079
```
6180

62-
**Updating screenshots:** Screenshot baselines should only be updated in headless mode so they match CI and stay consistent across devices. Use the dedicated command:
81+
To update screenshot baselines, run:
6382

6483
```sh
6584
yarn vitest:update
6685
```
6786

68-
This runs the full suite headlessly with the `--update` flag, regenerating any screenshot baselines that have changed. Commit the updated `.png` files alongside your code changes.
69-
Please be selective in pushing up changes to screenshots and only update files that you have added or expected to change. Pushing up all changes can make it hard to review PRs with small image differences based on different devices or environments that wouldn't trigger failures in CI.
87+
Only update screenshots that are intentionally affected by your change.
7088

71-
### Markdown Codeblock Tests
89+
### Markdown Example and Link Checks
7290

73-
We check the validity of our code examples marked with:
91+
`yarn test` runs both of the following:
7492

75-
- ` ```res ` (ReScript code snippet)
76-
- ` ```res sig ` (signature)
77-
- ` ```res prelude ` (ReScript code snippet available for all subsequent code snippets)
93+
- `scripts/test-examples.mjs` to validate ReScript code examples in markdown
94+
- `scripts/test-hrefs.mjs` to validate relative markdown links under `markdown-pages/`
7895

79-
Run the checks with:
96+
Supported ReScript markdown code fences:
8097

81-
```sh
82-
yarn test
83-
```
98+
- ` ```res `
99+
- ` ```res sig `
100+
- ` ```res prelude `
84101

85-
Refresh stale or missing JS Output fences with:
102+
Refresh generated JS output fences with:
86103

87104
```sh
88105
yarn test --update
89106
```
90107

91-
If you only want to run the example checker directly, you can still use:
108+
You can also run the scripts directly:
92109

93110
```sh
94111
node scripts/test-examples.mjs
95112
node scripts/test-examples.mjs --update
96-
```
97-
98-
### Markdown Hyperlink Tests
99-
100-
We are also verifying markdown href links to relative resources (via
101-
`[text](url)` syntax) with our `scripts/test-hrefs.js` script. Here is a short
102-
explanation on how the href testing works:
103-
104-
Domain relative links, such as `/docs/manual/latest`, `./introduction`,
105-
`introduction`, `/docs/foo/introduction.md` will be verified. That means the
106-
tester will check if given path exists in the `pages` directory.
107-
108-
If there are any anchor refs, such as `/docs/manual#test`, then the anchor will
109-
be ignored for the specific file path check. If there are any hrefs with `.md`,
110-
`.mdx` or `.html` file extension, then those will be stripped before the check
111-
happens (the markdown renderer drops file extensions on relative links as
112-
well).
113-
114-
External hrefs, such as `https://www.hello.world`, `//www.hello.world` will NOT be
115-
checked since they are assumed to be external resources.
116-
117-
Here is an example on how to run the tests:
118-
119-
```sh
120-
# Tests all files
121113
node scripts/test-hrefs.mjs
122-
123-
# Or just a subset (glob pattern)
124-
node scripts/test-hrefs.mjs "pages/docs/manual/**/*.mdx"
114+
node scripts/test-hrefs.mjs "markdown-pages/docs/manual/**/*.mdx"
125115
```
126116

127-
### Continous Integration
128-
129-
Always make sure to run `yarn test` before pushing any content, otherwise our CI
130-
might trigger a failure warning. Failing branches are very unlikely to be merged.
131-
132-
## Design / UX
133-
134-
Design mockups can be found
135-
[here](https://xd.adobe.com/spec/1cd19c3a-a0bb-4f93-4e11-725589888696-6ae0/grid/).
136-
137-
Be aware that some screen designs might still be work in progress, if you have
138-
any design / UX questions, either comment directly on the design tool as guest,
139-
or open an issue.
140-
141-
## Useful commands
142-
143-
Build CSS seperately via `npx postcss` (useful for debugging)
144-
145-
```sh
146-
# Devmode
147-
npx postcss styles/main.css -o test.css
148-
149-
# Production
150-
NODE_ENV=production npx postcss styles/main.css -o test.css
151-
```
117+
Run `yarn test` before pushing content changes so CI does not fail on markdown regressions.
152118

153119
## Writing Blog Posts
154120

155-
In case you are a blog author, please refer to our [guide on writing blog posts](https://rescript-lang.org/blogpost-guide).
121+
If you are writing a blog post, refer to the [blog post guide](https://rescript-lang.org/blogpost-guide).
156122

157-
## How to Add Your Company Logo to Our Front Page
123+
## Adding Your Company Logo
158124

159-
In case your company is a user of ReScript and wants to be displayed on our front page ("Trusted by our users" section), do the following:
125+
If your company uses ReScript and should appear in the "Trusted by our users" section on the front page:
160126

161-
- Get your logo as a black / white `.svg` version and use `#979AAD` as a fill color (check out the existing logos on our front page).
162-
- Put your logo into the [`app/public/lp`](./app/public/lp) folder; the file should be named after your company.
163-
- Open [src/common/OurUsers.res](./src/common/OurUsers.res) and add your info
127+
- Add a black and white `.svg` logo using `#979AAD` as the fill color.
128+
- Put the file in [`public/lp`](public/lp).
129+
- Update [`src/common/OurUsers.res`](src/common/OurUsers.res).
164130
- Commit, push, and open a PR.
165131

166-
### Contributing
132+
## Contributing
167133

168-
Please make sure to first read and comply to our [Code of Conduct](CODE_OF_CONDUCT.md) and check out our [CONTRIBUTING.md](CONTRIBUTING.md) file to learn how to get started with our contribution process!
134+
Please read and comply with our [Code of Conduct](CODE_OF_CONDUCT.md) and review [CONTRIBUTING.md](CONTRIBUTING.md) before contributing.

0 commit comments

Comments
 (0)