Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rescript-lang/rescript-lang.org
Official documentation website for the ReScript programming language
https://github.com/rescript-lang/rescript-lang.org
Last synced: 2 days ago
JSON representation
Official documentation website for the ReScript programming language
- Host: GitHub
- URL: https://github.com/rescript-lang/rescript-lang.org
- Owner: rescript-lang
- License: mit
- Created: 2020-08-06T07:52:36.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-23T09:15:31.000Z (21 days ago)
- Last Synced: 2024-11-06T03:04:04.596Z (7 days ago)
- Language: MDX
- Homepage: https://rescript-lang.org
- Size: 18.7 MB
- Stars: 1,852
- Watchers: 22
- Forks: 247
- Open Issues: 80
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](CODE_OF_CONDUCT.md)
# rescript-lang.org
This is the official documentation platform for the [ReScript](https://rescript-lang.org) programming language.
**Please report any technical issues with ReScript to the [compiler repository](https://github.com/rescript-lang/rescript-compiler).**
**In case you are missing some specific documentation:**
- Some language / compiler feature may not be documented yet
- Create an issue to let us know what you are missing
- In case you want to contribute missing docs, please refer to our [Contribution section](#contributing)
## System Requirements
- `node@20` or higher
- `npm@10` or higher
## Setup
```sh
# For first time clone / build (install dependencies)
npm i
# Initial build
npx rescript
# Build the index data. Only needed for initial clone (or content H2 changes)
npm run update-index
# In a new tab
npm run dev
open localhost:3000
```
In case you want to run ReScript in watchmode:
```sh
npx rescript -w
```
## Build Index Data
We are parsing our content for specific index data (such as, all interesting
search terms we need for searching inside the `Belt` docs). You can create your
index by running following command:
```sh
npm run update-index
```
All the index data is stored in `index_data`, but will not be tracked by git.
Make sure to build the index after a fresh clone, otherwise Next might not
build specific pages (file `index_data/x.json` not found).
## Project Structure Overview
- `data`: Contains hand-curated data, such as sidebar ordering, blog data, etc
- `index_data`: Contains generated data, usually generated by scripts like `scripts/extract-tocs.js`
- `compilers`: Contains a subdirectory with independently installed ReScript compilers, to be able to compile / test examples with different ReScript versions
- `misc_docs`: Contains `pages` independent resources that are embedded in miscellaneous pages (e.g. for the syntax lookup)
- `pages`: All Next pages. Those are written in JS / MDX, some pages are re-exporting ReScript based pages from the `src/` directory.
- `styles`: Contains all extra CSS that cannot be expressed with Tailwind
- `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
- `/bindings`: (Zero-cost) bindings to JS libraries / apis
- `/common`: ReScript modules that are neither `bindings`, nor `components`
- `/components`: ReScript / React components used by multiple pages
- `/ffi`: (to be deprecated) Plain JS that some ReScript code binds to (use `raw` statements for that)
- `/layouts`: All Next layouts used in our pages. Check out `src/common/App.res` for mapping layouts to routes
- `plugins`: Contains plugins for all kinds of things: HighlightJS, MDX, webpack loader, etc.
- `scripts`: Contains a mix of JS / ReScript based scripts that do all kind of code generation / code introspection logic
- `tailwind.config.js`: Contains our Tailwind configuration for all the low level design tokens
## Run Tests
### Markdown Codeblock Tests
We check the validity of our code examples marked with:
- ` ```res example ` (ReScript code snippet)
- ` ```res sig ` (signature)
- ` ```res prelude ` (ReScript code snippet available for all subsequent code snippets)
Run the checks with:
```sh
node scripts/test-examples.mjs
```
### Markdown Hyperlink Tests
We are also verifying markdown href links to relative resources (via
`[text](url)` syntax) with our `scripts/test-hrefs.js` script. Here is a short
explanation on how the href testing works:
Domain relative links, such as `/docs/manual/latest`, `./introduction`,
`introduction`, `/docs/foo/introduction.md` will be verified. That means the
tester will check if given path exists in the `pages` directory.
If there are any anchor refs, such as `/docs/manual#test`, then the anchor will
be ignored for the specific file path check. If there are any hrefs with `.md`,
`.mdx` or `.html` file extension, then those will be stripped before the check
happens (the markdown renderer drops file extensions on relative links as
well).
External hrefs, such as `https://www.hello.world`, `//www.hello.world` will NOT be
checked since they are assumed to be external resources.
Here is an example on how to run the tests:
```sh
# Tests all files
node scripts/test-hrefs.mjs
# Or just a subset (glob pattern)
node scripts/test-hrefs.mjs "pages/docs/manual/**/*.mdx"
```
### Continous Integration
Always make sure to run `npm test` before pushing any content, otherwise our CI
might trigger a failure warning. Failing branches are very unlikely to be merged.
## Design / UX
Design mockups can be found
[here](https://xd.adobe.com/spec/1cd19c3a-a0bb-4f93-4e11-725589888696-6ae0/grid/).
Be aware that some screen designs might still be work in progress, if you have
any design / UX questions, either comment directly on the design tool as guest,
or open an issue.
## Useful commands
Build CSS seperately via `npx postcss` (useful for debugging)
```sh
# Devmode
npx postcss styles/main.css -o test.css
# Production
NODE_ENV=production npx postcss styles/main.css -o test.css
```
## Writing Blog Posts
In case you are a blog author, please refer to our [guide on writing blog posts](https://rescript-lang.org/blogpost-guide).
## How to Add Your Company Logo to Our Front Page
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:
- 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).
- Put your logo into the [`public/static/lp`](./public/static/lp) folder; the file should be named after your company.
- Open [src/common/OurUsers.res](./src/common/OurUsers.res) and add your info
- Commit, push, and open a PR.
### Contributing
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!