docs: Use h1/h2 styling

Also start filling out sandbox section

docs/compatibility.md

@@ -1,5 +1,4 @@
-Compatibility
+# Compatibility
-=============
 
 Luau is based on Lua 5.1, and as such incorporates all features of 5.1, except for ones that had to be taken out due to sandboxing limitations. Because of backwards compatibility constraints, we don't remove features deprecated by later versions (e.g. we still support `getfenv`/`setfenv`). Later Lua versions introduce new features into the language and new libraries/functions.
 
@@ -13,8 +12,7 @@ Our overall goal is to incorporate features from the later versions of Lua when
 
 Please note that all of these decisions are not final, they are just our current stance. In some cases evolution of our VM may make a feature that was previously impractical to support due to performance complications feasible. In some cases a feature that didn't have a strong use case gains one, so we can implement it.
 
-Implementation limits
+## Implementation limits
-=====================
 
 Luau has certain limitations around the number of local variables, registers, upvalues, constants and instructions. These limits are often different from the limits imposed by various versions of Lua, and are documented here without promising that future versions will adhere to these. Note that writing code that is close to any of these limits is dangerous because this code may become invalid as our codegen evolves.
 
@@ -28,8 +26,7 @@ Luau has certain limitations around the number of local variables, registers, up
 
 Note that Lua 5.3 has a larger upvalue limit (255) and a larger constant limit (2^26); existing Luau limits are likely sufficient for reasonable use cases.
 
-Lua 5.1
+## Lua 5.1
-=======
 
 Since several features were removed from Lua 5.1 for sandboxing reasons, this table lists them for completeness.
 
@@ -42,8 +39,7 @@ Since several features were removed from Lua 5.1 for sandboxing reasons, this ta
 
 Sandboxing challenges are [covered in the dedicated section](sandbox.md).
 
-Lua 5.2
+## Lua 5.2
-=======
 
 | feature | status | notes |
 |---------|--------|------|
@@ -72,8 +68,7 @@ Two things that are important to call out here are various new metamethods for t
 
 For `__pairs`/`__ipairs`, we aren't sure that this is the right design choice - self-iterating tables via `__iter` are very appealing, and if we can resolve some challenges with array iteration order, that would make the language more accessible so we may go that route instead.
 
-Lua 5.3
+## Lua 5.3
-=======
 
 | feature | status | notes |
 |---------|--------|------|
@@ -94,8 +89,7 @@ If integers are taken out of the equation, bitwise operators make much less sens
 
 Floor division is less harmful, but it's used rarely enough that `math.floor(a/b)` seems like an adequate replacement; additionally, `//` is a comment in C-derived languages and we may decide to adopt it in addition to `--` at some point.
 
-Lua 5.4
+## Lua 5.4
-=======
 
 | feature | status | notes |
 |--|--|--|

docs/index.md

@@ -1,5 +1,4 @@
-Luau
+# Luau
-====
 
 Luau is a fast, small, safe, gradually typed embeddable scripting language derived from Lua. It is used by Roblox game developers to write game code, as well as by Roblox engineers to implement large parts of the user-facing application code as well as portions of the editor (Roblox Studio) as plugins.
 
@@ -12,38 +11,31 @@ print(p.x, p.y)
 -- print(p.z) results in a type error
 ```
 
-Motivation
+## Motivation
-==========
 
 Around 2006, [Roblox](https://www.roblox.com) started using Lua 5.1 as a scripting language for games. Over the years we ended up substantially evolving the implementation and the language; to support growing sophistication of games on the Roblox platform, growing team sizes and large internal teams writing a lot of code for application/editor (400KLOC as of 2020), we had to invest in performance, ease of use and language tooling, and introduce a gradual type system to the language. [This page](why.md) goes into more detail about the road that got us here.
 
-Syntax
+## Syntax
-======
 
 Luau is syntactically backwards-compatible with Lua 5.1 (code that is valid Lua 5.1 is also valid Luau); however, we have extended the language with a set of syntactical features that make the language more familiar and ergonomic. The syntax [is described here](syntax.md).
 
-Sandboxing
+## Sandboxing
-==========
 
 Luau limits the set of standard libraries exposed to the users and implements extra sandboxing features to be able to run unprivileged code (written by our game developers) side by side with privileged code (written by us). This results in an execution environment that is different from what is commonplace in Lua. The sandboxing [is described here](sandbox.md).
 
 
-Compatibility
+## Compatibility
-=============
 
 Whenever possible, Luau aims to be backwards-compatible with Lua 5.1 and at the same time to incorporate features from later revisions of Lua. However, Luau is not a full superset of later versions of Lua - we do not agree with some design decisions and are not constrained by the same reasoning as that of PUC-Rio. All post-5.1 Lua features, along with their support status in Luau, [are documented here](compatibility.md).
 
-Analysis
+## Analysis
-========
 
 To make it easier to write correct code, Luau comes with a set of analysis tools that can surface common mistakes. These consist of a linter and a type checker, colloquially known as "script analysis", and can be used from [Roblox Studio](https://developer.roblox.com/en-us/articles/The-Script-Analysis-Tool) or using SECRET TOOL. The linting passes are [described here](lint.md), and the type checking user guide can [be found here](typecheck.md).
 
-Libraries
+## Libraries
-=========
 
 As a language, Luau is a full superset of Lua 5.1. As far as standard library is concerned, some functions had to be removed from the builtin libraries, and some functions had to be added. Additionally, Luau is currently only runnable from the context of the Roblox engine, which exposes a large API surface [documented on Roblox developer portal](https://developer.roblox.com/en-us/api-reference).
 
-Performance
+## Performance
-===========
 
 In addition to a completely custom front end that implements parsing, linting and type checking, Luau runtime features new bytecode, interpreter and compiler that are heavily tuned for performance. Luau currently does not implement Just-In-Time compilation, but its interpreter is often competitive with LuaJIT interpreter on a wide set of benchmarks. We continue to optimize the runtime and rewrite portions of it to be even more efficient, including plans for a new garbage collector and further library optimizations, as well as an eventual JIT/AOT option. While our overall goal is to minimize the amount of time programmers spend tuning performance, some details about the performance characteristics are [provided for inquisitive minds](performance.md).

docs/lint.md

@@ -1,5 +1,4 @@
-Linting
+# Linting
-=======
 
 Luau comes with a set of linting passes, that help make sure that the code is correct and consistent. Unlike the type checker, that models the behavior of the code thoroughly and points toward type mismatches that are likely to result in runtime errors, the linter is more opinionated and produces warnings that can often be safely ignored, although it's recommended to keep the code clean of the warnings.
 
@@ -7,8 +6,7 @@ Linter produces many different types of warnings; many of these are enabled by d
 
 The rest of this page documents all warnings produced by the linter; each warning has a name and a numeric code, the latter is used when displaying warnings.
 
-UnknownGlobal (1)
+## UnknownGlobal (1)
-===
 
 By default, variables in Luau are global (this is inherited from Lua 5.x and can't be changed because of backwards compatibility). This means that typos in identifiers are invisible to the parser, and often break at runtime. For this reason, the linter considers all globals that aren't part of the builtin global table and aren't explicitly defined in the script "unknown":
 
@@ -21,8 +19,7 @@ print(displaName)
 
 Note that injecting globals via `setfenv` can produce this warning in correct code; global injection is incompatible with type checking and has performance implications so we recommend against it and in favor of using `require` with correctly scoped identifiers.
 
-DeprecatedGlobal (2)
+## DeprecatedGlobal (2)
-===
 
 Some global names exist for compatibility but their use is discouraged. This mostly affects globals introduced by Roblox, and since they can have problematic behavior or can break in the future, this warning highlights their uses:
 
@@ -33,8 +30,7 @@ ypcall(function()
 end)
 ```
 
-GlobalUsedAsLocal (3)
+## GlobalUsedAsLocal (3)
-===
 
 The UnknownGlobal lint can catch typos in globals that are read, but can't catch them in globals that are assigned to. Because of this, and to discourage the use of globals in general, linter detects cases when a global is only used in one function and can be safely converted to a local variable. Note that in some cases this requires declaring the local variable in the beginning of the function instead of where it's being assigned to.
 
@@ -50,8 +46,7 @@ local function testFunc(a)
 end
 ```
 
-LocalShadow (4)
+## LocalShadow (4)
-===
 
 In Luau, it is valid to shadow locals and globals with a local variable, including doing it in the same function. This can result in subtle bugs, since the shadowing may not be obvious to the reader. This warning detects cases where local variables shadow other local variables in the same function, or global variables used in the script; for more cases of detected shadowing see `LocalShadowPedantic`.
 
@@ -66,8 +61,7 @@ local function foo()
 end
 ```
 
-SameLineStatement (5)
+## SameLineStatement (5)
-===
 
 Luau doesn't require the use of semicolons and doesn't automatically insert them at line breaks. When used wisely this results in code that is easy to read and understand, however it can cause subtle issues and hard to understand code when abused by using many different statements on the same line. This warning highlights cases where code should either be broken into multiple lines, or use `;` as a visual guide.
 
@@ -76,8 +70,7 @@ Luau doesn't require the use of semicolons and doesn't automatically insert them
 if b < 0 then local a = b + 1 print(a, b) end
 ```
 
-MultiLineStatement (6)
+## MultiLineStatement (6)
-===
 
 An opposite problem is having statements that span multiple lines. This is good for readability when the code is indented properly, but when it's not it results in code that's hard to understand, as its easy to confuse the next line for a separate statement.
 
@@ -87,8 +80,7 @@ print(math.max(1,
 math.min(2, 3)))
 ```
 
-LocalUnused (7)
+## LocalUnused (7)
-===
 
 This warning is one of the few warnings that highlight unused variables. Local variable declarations that aren't used may indicate a bug in the code (for example, there could be a typo in the code that uses the wrong variable) or redundant code that is no longer necessary (for example, calling a function to get its result and never using this result). This warning warns about locals that aren't used; if the locals are not used intentionally they can be prefixed with `_` to silence the warning:
 
@@ -99,8 +91,7 @@ local y = 2
 print(x, x)
 ```
 
-FunctionUnused (8)
+## FunctionUnused (8)
-===
 
 While unused local variables could be useful for debugging, unused functions usually contain dead code that was meant to be removed. Unused functions clutter code, can be a result of typos similar to local variables, and can mislead the reader into thinking that some functionality is supported.
 
@@ -115,8 +106,7 @@ end
 return foo()
 ```
 
-ImportUnused (9)
+## ImportUnused (9)
-===
 
 In Luau, there's no first-class module system that's part of the syntax, but `require` function acts as an import statement. When a local is initialized with a `require` result, and the local is unused, this is classified as "unused import". Removing unused imports improves code quality because it makes it obvious what the dependencies of the code are:
 
@@ -125,8 +115,7 @@ In Luau, there's no first-class module system that's part of the syntax, but `re
 local Roact = require(game.Packages.Roact)
 ```
 
-BuiltinGlobalWrite (10)
+## BuiltinGlobalWrite (10)
-===
 
 While the sandboxing model of Luau prevents overwriting built-in globals such as `table` for the entire program, it's still valid to reassign these globals - this results in "global shadowing", where the script's global table contains a custom version of `table` after writing to it. This is problematic because it disables some optimizations, and can result in misleading code. When shadowing built-in globals, use locals instead.
 
@@ -135,8 +124,7 @@ While the sandboxing model of Luau prevents overwriting built-in globals such as
 math = {}
 ```
 
-PlaceholderRead (11)
+## PlaceholderRead (11)
-===
 
 `_` variable name is commonly used as a placeholder to discard function results. The linter follows this convention and doesn't warn about the use of `_` in various cases where a different name would cause a warning otherwise. To make sure the placeholder is only used to write values to it, this warning detects the cases where it's read instead:
 
@@ -146,8 +134,7 @@ local _ = 5
 return _
 ```
 
-UnreachableCode (12)
+## UnreachableCode (12)
-===
 
 In some cases the linter can detect code that is never executed, because all execution paths through the function exit the function or the loop before reaching it. Such code is misleading because it's not always obvious to the reader that it never runs, and as such it should be removed.
 
@@ -163,8 +150,7 @@ function cbrt(v)
 end
 ```
 
-UnknownType (13)
+## UnknownType (13)
-===
 
 Luau provides several functions to get the value type as a string (`type`, `typeof`), and some Roblox APIs expose class names through string arguments (`Instance.new`). This warning detects incorrect use of the type names by checking the string literals used in type comparisons and function calls.
 
@@ -175,8 +161,7 @@ if type(v) == "String" then
 end
 ```
 
-ForRange (14)
+## ForRange (14)
-===
 
 When using a numeric for, it's possible to make various mistakes when specifying the for bounds. For example, to iterate through the table backwards, it's important to specify the negative step size. This warning detects several cases where the numeric for only runs for 0 or 1 iterations, or when the step doesn't divide the size of the range evenly.
 
@@ -186,8 +171,7 @@ for i=#t,1 do
 end
 ```
 
-UnbalancedAssignment (15)
+## UnbalancedAssignment (15)
-===
 
 Assignment statements and local variable declarations in Luau support multiple variables on the left side and multiple values on the right side. The number of values doesn't need to match; when the right side has more values, the extra values are discarded, and then the left side has more variables the extra variables are set to `nil`. However, this can result in subtle bugs where a value is omitted mistakenly. This warning warns about cases like this; if the last expression on the right hand side returns multiple values, the warning is not emitted.
 
@@ -196,8 +180,7 @@ Assignment statements and local variable declarations in Luau support multiple v
 local x, y, z = 1, 2
 ```
 
-ImplicitReturn (16)
+## ImplicitReturn (16)
-===
 
 In Luau, there's a subtle difference between returning no values from a function and returning `nil`. In many contexts these are equivalent, but when the results are passed to a variadic function (perhaps implicitly), the difference can be observed - for example, `print(foo())` prints nothing if `foo` returns no values, and `nil` if it returns `nil`.
 
@@ -214,7 +197,6 @@ local function find(t, expected)
 end
 ```
 
-LocalShadowPedantic (17)
+## LocalShadowPedantic (17)
-===
 
 This warning extends `LocalShadow` by also warning about cases where a local variable shadows a local variable with the same name from a parent function, or when it shadows a builtin global. This warning tends to be noisy and as such is disabled by default.

docs/performance.md

@@ -1,2 +1,2 @@
-Performance
+# Performance
-===========
+

docs/sandbox.md

@@ -1,2 +1,9 @@
-Sandboxing
+# Sandboxing
-==========
+
+Luau is safe to embed. Broadly speaking, this means that even in the face of untrusted (and in Roblox case, actively malicious) code, the language and the standard library don't allow any unsafe access to the underlying system, and don't have any bugs that allow escaping out of the sandbox (e.g. to gain native code execution through ROP gadgets et al). Additionally, the VM provides extra features to implement isolation of privileged code from unprivileged code and protect one from the other; this is important if the embedding environment (Roblox) decides to expose some APIs that may not be safe to call from untrusted code, for example because they do provide controlled access to the underlying system or risk PII exposure through fingerprinting etc.
+
+This safety is achieved through a combination of removing features from the standard library that are unsafe, adding features to the VM that make it possible to implement sandboxing and isolation, and making sure the implementation is safe from memory safety issues using fuzzing.
+
+Of course, since the entire stack is implemented in C++, the sandboxing isn't provable - in theory, compiler or the standard library can have exploitable vulnerabilities. In practice these are usually found and fixed quickly. While implementing the stack in a safer language such as Rust would make it easier to provide these guarantees, to our knowledge (based on existing code) this would make it impossible to reach the level of performance required.
+
+## Library

docs/syntax.md

@@ -1,5 +1,4 @@
-Syntax
+# Syntax
-======
 
 Luau uses the baseline [syntax of Lua 5.1](https://www.lua.org/manual/5.1/manual.html#2). For detailed documentation, please refer to the Lua manual, this is an example:
 
@@ -30,8 +29,7 @@ Note that future versions of Lua extend the Lua 5.1 syntax with the following fe
 
 The rest of this document documents additional syntax used in Luau.
 
-String literals
+## String literals
-===============
 
 As noted above, Luau implements support for hexadecimal (`\0x`), Unicode (`\u`) and `\z` escapes for string literals. This syntax follows [Lua 5.3 syntax](https://www.lua.org/manual/5.3/manual.html#3.1):
 
@@ -39,8 +37,7 @@ As noted above, Luau implements support for hexadecimal (`\0x`), Unicode (`\u`)
 - `\u{ABC}` inserts a UTF8 byte sequence that encodes U+0ABC character into the string (note that braces are mandatory)
 - `\z` at the end of the line inside a string literal ignores all following whitespace including newlines, which can be helpful for breaking long literals into multiple lines.
 
-Number literals
+## Number literals
-===============
 
 In addition to basic integer and floating-point decimal numbers, Luau supports:
 
@@ -50,8 +47,7 @@ In addition to basic integer and floating-point decimal numbers, Luau supports:
 
 Note that Luau only has a single number type, a 64-bit IEEE754 double precision number (which can represent integers up to 2^53 exactly), and larger integer literals are stored with precision loss.
 
-Continue statement
+## Continue statement
-==================
 
 In addition to `break` in all loops, Luau supports `continue` statement. Similar to `break`, `continue` must be the last statement in the block.
 
@@ -80,8 +76,7 @@ repeat
 until a > 0
 ```
 
-Compound assignments
+## Compound assignments
-====================
 
 Luau supports compound assignments with the following operators: `+=`, `-=`, `*=`, `/=`, `%=`, `^=`, `..=`. Just like regular assignments, compound assignments are statements, not expressions:
 
@@ -105,8 +100,7 @@ a[foo()] += 1
 
 Compound assignments call the arithmetic metamethods (`__add` et al) and table indexing metamethods (`__index` and `__newindex`) as needed - for custom types no extra effort is necessary to support them.
 
-Type annotations
+## Type annotations
-================
 
 To support gradual typing, Luau supports optional type annotations for variables and functions, as well as declaring type aliases.
 

docs/typecheck.md

@@ -1,4 +1,3 @@
-Type checking
+# Type checking
-=============
 
 Luau supports a gradual type system through the use of type annotations and type inference. Once someone gets around to writing this, this will have documentation on the details of the type system and examples of common problems/how to deal with them.

docs/why.md

@@ -1,5 +1,4 @@
-Why Luau?
+# Why Luau?
-=========
 
 Around 2006, [Roblox](https://www.roblox.com) started using Lua 5.1 as a scripting language for games. Over the years the runtime had to be tweaked to provide a safe, secure sandboxed environment; we gradually started accumulating small library changes and tweaks.
 
@@ -11,8 +10,7 @@ Unlike mainline Lua, we also could not afford to do major breaking changes to th
 
 All of these motivated us to start reshaping Lua 5.1 that we started from into a new, derivative language that we call Luau. Our focus is on making the language more performant and feature-rich, and make it easier to write robust code through a combination of linting and type checking using a gradual type system.
 
-Complete rewrite?
+## Complete rewrite?
-=================
 
 A very large part of Luau codebase is written from scratch. We needed a set of tools to be able to write language analysis tools; Lua has a parser that is integrated with the bytecode compiler, which makes it unsuitable for complex semantic analysis. For bytecode compilation, while a single pass compiler can deliver better compilation throughput and be simpler than a full frontend/backend, it significantly limits the optimizations that can be done at the bytecode level.