探客时代
ReScript
The JavaScript-like language you have been waiting for
README
rescript-lang.org
This is the official documentation platform for the ReScript programming language.
In case you want to report a technical issue, please refer to the appropriate repository:
- rescript-compiler: The compiler and build system
- rescript-syntax: The ReScript syntax
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
System Requirements
- node@12.22.1 or higher (for ES6 module compat)
- npm@7 (package-lock v2)
Setup
- ```sh
- # For first time clone / build (install dependencies)
- npm i
- # Only needed for initial clone (or content H2 changes)
- npm run update-index
- # Initial build
- npx rescript
- # Build the index data
- 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 build -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 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.
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.
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 and add your info
- Commit, push, and open a PR.
Contributing
Please make sure to first read and comply to our Code of Conduct and check out our CONTRIBUTING.md file to learn how to get started with our contribution process!
