diff --git a/markdown-pages/docs/manual/converting-from-js.mdx b/markdown-pages/docs/manual/converting-from-js.mdx index 75fd1ae82..4a8c615c2 100644 --- a/markdown-pages/docs/manual/converting-from-js.mdx +++ b/markdown-pages/docs/manual/converting-from-js.mdx @@ -8,6 +8,8 @@ order: 1 # Converting from JS +If you want a quick syntax guide before starting a migration, see [ReScript for JavaScript Developers](./rescript-for-javascript-developers.mdx). + ReScript offers a unique project conversion methodology which: - Ensures minimal disruption to your teammates (very important!). diff --git a/markdown-pages/docs/manual/editor-plugins.mdx b/markdown-pages/docs/manual/editor-plugins.mdx index e2a93abcf..2e2514651 100644 --- a/markdown-pages/docs/manual/editor-plugins.mdx +++ b/markdown-pages/docs/manual/editor-plugins.mdx @@ -4,7 +4,7 @@ metaTitle: "Editor" description: "Documentation about ReScript editor plugins and code analysis" canonical: "/docs/manual/editor-plugins" section: "Overview" -order: 3 +order: 4 --- # Editor diff --git a/markdown-pages/docs/manual/introduction.mdx b/markdown-pages/docs/manual/introduction.mdx index 3a46b8873..eb5fb8993 100644 --- a/markdown-pages/docs/manual/introduction.mdx +++ b/markdown-pages/docs/manual/introduction.mdx @@ -16,6 +16,8 @@ ReScript compiles to clean, readable, and performant JavaScript, directly runnab Your existing knowledge of web development transfers to ReScript projects. +If you are coming from JavaScript, start with [ReScript for JavaScript Developers](./rescript-for-javascript-developers.mdx) for a quick syntax guide. + ReScript code can be [imported into JavaScript code](./import-from-export-to-js.mdx#export-to-javascript), can [generate types for TypeScript](./typescript-integration.mdx), and ReScript can [import code written in JavaScript or TypeScript](./import-from-export-to-js.mdx#import-from-javascript). ## Type System diff --git a/markdown-pages/docs/manual/llms.mdx b/markdown-pages/docs/manual/llms.mdx index 7e73b6153..1e89e09cf 100644 --- a/markdown-pages/docs/manual/llms.mdx +++ b/markdown-pages/docs/manual/llms.mdx @@ -3,7 +3,7 @@ title: "LLMs" description: "Documentation for LLMs" canonical: "/docs/manual/llms" section: "Overview" -order: 4 +order: 10 --- # Documentation for LLMs diff --git a/markdown-pages/docs/manual/migrate-to-v12.mdx b/markdown-pages/docs/manual/migrate-to-v12.mdx index 8b50fdf94..684405dbe 100644 --- a/markdown-pages/docs/manual/migrate-to-v12.mdx +++ b/markdown-pages/docs/manual/migrate-to-v12.mdx @@ -3,7 +3,7 @@ title: "Migrate to v12" description: "Instructions on upgrading to ReScript 12" canonical: "/docs/manual/migrate-to-v12" section: "Overview" -order: 4 +order: 5 --- # Migrate to ReScript 12 diff --git a/markdown-pages/docs/manual/overview.mdx b/markdown-pages/docs/manual/overview.mdx index 94dafc278..e9ce379aa 100644 --- a/markdown-pages/docs/manual/overview.mdx +++ b/markdown-pages/docs/manual/overview.mdx @@ -11,6 +11,8 @@ order: 1 A concise reference of ReScript's syntax and core language features. +If you already know JavaScript and want a quick syntax guide first, see [ReScript for JavaScript Developers](./rescript-for-javascript-developers.mdx). + ## Semicolons ReScript does not require semicolons. Line breaks are sufficient to separate statements. diff --git a/markdown-pages/docs/manual/rescript-for-javascript-developers.mdx b/markdown-pages/docs/manual/rescript-for-javascript-developers.mdx new file mode 100644 index 000000000..f8de11bf7 --- /dev/null +++ b/markdown-pages/docs/manual/rescript-for-javascript-developers.mdx @@ -0,0 +1,56 @@ +--- +title: "ReScript for JavaScript Developers" +description: "A quick ReScript syntax guide for JavaScript developers" +canonical: "/docs/manual/rescript-for-javascript-developers" +section: "Overview" +order: 3 +--- + +# ReScript for JavaScript Developers + +If you already write JavaScript, ReScript should feel familiar quickly. This page is a compact syntax guide for the main differences you should be aware of. + +For a guided migration workflow, see [Converting from JS](./converting-from-js.mdx). + +## What to know first + +- `let` bindings are immutable by default. See [Let Binding](./let-binding.mdx) and [Mutation](./mutation.mdx). +- ReScript does not use `null` and `undefined` as normal control flow. Reach for `option` instead. See [Null, Undefined and Option](./null-undefined-option.mdx). +- Arrays must contain values of the same type. See [Array and List](./array-and-list.mdx) and [Tuple](./tuple.mdx). +- Records are not ad-hoc JS objects; they have known field names and types. See [Record](./record.mdx) and [Object](./object.mdx). +- Conditionals and blocks return values, so expression-oriented code is common. See [If-Else & Loops](./control-flow.mdx). +- Pattern matching replaces many ad-hoc `if` or property-check branches. See [Pattern Matching / Destructuring](./pattern-matching-destructuring.mdx). + +## Quick reference + +| Topic | ReScript | Notes for JavaScript developers | +| --------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Semicolons | `let x = 1` | Semicolons are not required. See [Overview](./overview.mdx#semicolons). | +| Comments | `//`, `/* */`, `/** */` | Familiar syntax, including doc comments. See [Overview](./overview.mdx#comments). | +| Variables | `let x = 5` | `let` creates an immutable binding. See [Let Binding](./let-binding.mdx). | +| Mutation | `let x = ref(5)` | Mutable state is explicit through `ref` or mutable fields. See [Mutation](./mutation.mdx). | +| Strings | `"hello"` | Strings use double quotes. See [Primitive Types](./primitive-types.mdx). | +| String concatenation | `"hello " ++ name` | ReScript uses `++` for strings. See [Primitive Types](./primitive-types.mdx). | +| Interpolation | `` `hello ${name}` `` | Template strings work similarly. See [Primitive Types](./primitive-types.mdx). | +| Equality | `===`, `!==`, `==`, `!=` | No coercive equality. `==` and `!=` are structural. See [Equality and Comparison](./equality-comparison.mdx). | +| Numbers | `3`, `3.14`, `2.0 * 3.0` | Arithmetic operators work for both `int` and `float`. See [Primitive Types](./primitive-types.mdx). | +| Records | `{x: 30, y: 20}` | Similar object syntax, but records are typed. See [Record](./record.mdx). | +| Arrays | `[1, 2, 3]` | Arrays are homogeneous. See [Array and List](./array-and-list.mdx). | +| Mixed fixed-size data | `(1, "Bob", true)` | Use tuples instead of heterogeneous arrays. See [Tuple](./tuple.mdx). | +| Missing values | `option<'a>` | Use `Some(value)` and `None` instead of `null` and `undefined`. See [Null, Undefined and Option](./null-undefined-option.mdx). | +| Functions | `let add = (a, b) => a + b` | Familiar arrow-style syntax. See [Function](./function.mdx). | +| Blocks | `{ let x = 1; x + 1 }` | The last expression is returned implicitly. See [Overview](./overview.mdx#blocks). | +| Conditionals | `if cond {a} else {b}` | `if` is an expression. See [If-Else & Loops](./control-flow.mdx). | +| Pattern matching | `switch value { ... }` | Use `switch` for destructuring and exhaustive branching. See [Pattern Matching / Destructuring](./pattern-matching-destructuring.mdx). | +| Destructuring | `let {a, b} = data` | Works for records, arrays, tuples, and more. See [Pattern Matching / Destructuring](./pattern-matching-destructuring.mdx). | +| Loops | `for i in 0 to 10 {}` | `for` and `while` exist, but collection transforms are also common. See [If-Else & Loops](./control-flow.mdx). | +| Exceptions | `throw(MyException(...))` | `throw` and `try` exist, but typed data flow is preferred where possible. See [Exception](./exception.mdx). | +| JSX | `` | JSX is supported directly, with a few ReScript conventions. See [JSX](./jsx.mdx). | + +## Where to Go Next + +- For a broader syntax reference, see [Overview](./overview.mdx). +- For a migration workflow inside an existing codebase, see [Converting from JS](./converting-from-js.mdx). +- For JavaScript interop, see [Interop Cheatsheet](./interop-cheatsheet.mdx). +- For importing and exporting JS modules, see [Import from Export to JS](./import-from-export-to-js.mdx). +- For binding to JS objects and functions, see [Bind to JS Object](./bind-to-js-object.mdx) and [Bind to JS Function](./bind-to-js-function.mdx). diff --git a/src/Mdx.res b/src/Mdx.res index 9eccb018a..cadf676c5 100644 --- a/src/Mdx.res +++ b/src/Mdx.res @@ -59,10 +59,14 @@ external childrenToString: {..} => string = "toString" let sortSection = mdxPages => Array.toSorted(mdxPages, (a: attributes, b: attributes) => switch (a.order, b.order) { - | (Some(a), Some(b)) => a > b ? 1.0 : -1.0 + | (Some(orderA), Some(orderB)) => + switch Int.compare(orderA, orderB) { + | 0. => String.compare(a.title, b.title) + | result => result + } | (Some(_), None) => -1.0 | (None, Some(_)) => 1.0 - | (None, None) => 0.0 + | (None, None) => String.compare(a.title, b.title) } )