docs: add page for rescript for javascript developers

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!).

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

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

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

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

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.

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                   | `<Comp message />`          | 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).

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)
     }
   )