diff --git a/docs/_pages/getting-started.md b/docs/_pages/getting-started.md
index 0252d786..095cc2ab 100644
--- a/docs/_pages/getting-started.md
+++ b/docs/_pages/getting-started.md
@@ -1,5 +1,155 @@
---
permalink: /getting-started
title: Getting Started
+toc: true
---
+To get started with Luau you need to install Roblox Studio, which you can download [here](https://www.roblox.com/create).
+
+## Creating a place
+
+If you just want to experiment with the language itself, you can create a simple baseplate game.
+
+
+
+
+
+## Creating a script
+
+To create your own testing script, go to ServerScriptService in the explorer tree and add a Script object.
+
+
+
+
+
+Double-click on the script object and paste this:
+
+```lua
+function ispositive(x)
+ return x > 0
+end
+
+print(ispositive(1))
+print(ispositive("2"))
+
+function isfoo(a)
+ return a == "foo"
+end
+
+print(isfoo("bar"))
+print(isfoo(1))
+```
+
+Note that there are no warnings about calling ``ispositive()`` with a string, or calling ``isfoo()`` a number.
+
+## Enabling type inference
+
+Now modify the script to include ``--!strict`` at the top:
+
+```lua
+--!strict
+
+function ispositive(x)
+ return x > 0
+end
+
+print(ispositive(1))
+print(ispositive("2"))
+
+function isfoo(a)
+ return a == "foo"
+end
+
+print(isfoo("bar"))
+print(isfoo(1))
+```
+
+Note that the editor now highlights the incorrect calls to ``ispositive()`` and ``isfoo()``.
+
+
+
+
+
+
+## Annotations
+
+You can add annotations to locals, arguments, and function return types. Among other things, annotations can help enforce that you don't accidentally do something stupid. Here's how we would add annotations to ``ispositive()``:
+
+```lua
+--!strict
+
+function ispositive(x : number) : boolean
+ return x > 0
+end
+
+local result : boolean
+result = ispositive(1)
+
+```
+
+Everything is good. We've told the editor that ``ispositive()`` accepts a number and returns a boolean, and that's how we're using it. But imagine that later we decide to change ``ispositive()`` to return a string value:
+
+```lua
+--!strict
+
+function ispositive(x : number) : boolean
+ if x > 0 then
+ return "yes"
+ else
+ return "no"
+ end
+end
+
+local result : boolean
+result = ispositive(1)
+```
+
+Oops -- we're returning string values, but we forgot to update the function return type. Since ``print()`` accepts anything, the call to ``ispositive()`` is still valid. But because the annotation doesn't match our code, we get a warning in the function body itself:
+
+
+
+
+
+And then of course, the fix is simple; just change the annotation to declare the return type as a string.
+
+```lua
+--!strict
+
+function ispositive(x : number) : string
+ if x > 0 then
+ return "yes"
+ else
+ return "no"
+ end
+end
+
+local result : boolean
+result = ispositive(1)
+```
+
+Well, almost - we also declared result as a boolean, and now that's clearly wrong.
+
+
+
+
+
+So now we update the type of the local variable, and everything is good.
+
+```lua
+--!strict
+
+function ispositive(x : number) : string
+ if x > 0 then
+ return "yes"
+ else
+ return "no"
+ end
+end
+
+local result : string
+result = ispositive(1)
+```
+
+## Conclusions
+
+To dive into more areas of Luau, check out our main reference pages for [syntax](syntax) and [typechecking](typecheck)
diff --git a/docs/_pages/lint.md b/docs/_pages/lint.md
index 1309b23c..78db46d9 100644
--- a/docs/_pages/lint.md
+++ b/docs/_pages/lint.md
@@ -1,6 +1,7 @@
---
permalink: /lint
title: Linting
+toc: true
---
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.
diff --git a/docs/_pages/performance.md b/docs/_pages/performance.md
index 7ac7b197..1d25e4cb 100644
--- a/docs/_pages/performance.md
+++ b/docs/_pages/performance.md
@@ -1,6 +1,7 @@
---
permalink: /performance
title: Performance
+toc: true
---
One of main goals of Luau is to enable high performance code, with gameplay code being the main use case. This can be viewed as two separate goals:
diff --git a/docs/_pages/sandbox.md b/docs/_pages/sandbox.md
index 9162540f..e5d5e4d3 100644
--- a/docs/_pages/sandbox.md
+++ b/docs/_pages/sandbox.md
@@ -1,6 +1,7 @@
---
permalink: /sandbox
title: Sandboxing
+toc: true
---
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.
diff --git a/docs/_pages/syntax.md b/docs/_pages/syntax.md
index 6668e272..ce5ab049 100644
--- a/docs/_pages/syntax.md
+++ b/docs/_pages/syntax.md
@@ -1,6 +1,7 @@
---
permalink: /syntax
title: Syntax
+toc: true
---
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:
@@ -28,7 +29,7 @@ Note that future versions of Lua extend the Lua 5.1 syntax with the following fe
- floor division operator (`//`)
- `` and `` local attributes
-> For details please refer to [compatibility section](compatibility.md).
+> For details please refer to [compatibility section](compatibility).
The rest of this document documents additional syntax used in Luau.
@@ -153,4 +154,4 @@ By default type aliases are local to the file they are declared in. To be able t
export type Point = { x: number, y: number }
```
-For more information please refer to [typechecking documentation](typecheck.md).
+For more information please refer to [typechecking documentation](typecheck).
diff --git a/docs/_pages/typecheck.md b/docs/_pages/typecheck.md
index b5276c4e..74ffc30a 100644
--- a/docs/_pages/typecheck.md
+++ b/docs/_pages/typecheck.md
@@ -1,6 +1,7 @@
---
permalink: /typecheck
title: Type checking
+toc: true
---
Luau supports a gradual type system through the use of type annotations and type inference.
@@ -61,7 +62,7 @@ local b2: B = a1 -- not ok
## Primitive types
-Lua VM supports 8 primitive types: `nil`, `string`, `number`, `boolean`, `table`, `function`, `thread`, and `userdata`. Of these, `table` and `function` are not represented by name, but have their dedicated syntax as covered in this [syntax document](syntax.md), and `userdata` is represented by [concrete types](#Roblox-types); other types can be specified by their name.
+Lua VM supports 8 primitive types: `nil`, `string`, `number`, `boolean`, `table`, `function`, `thread`, and `userdata`. Of these, `table` and `function` are not represented by name, but have their dedicated syntax as covered in this [syntax document](syntax), and `userdata` is represented by [concrete types](#Roblox-types); other types can be specified by their name.
Additionally, we also have `any` which is a special built-in type. It effectively disables all type checking, and thus should be used as last resort.
diff --git a/docs/assets/images/create-new-place.png b/docs/assets/images/create-new-place.png
new file mode 100644
index 00000000..63a29242
Binary files /dev/null and b/docs/assets/images/create-new-place.png differ
diff --git a/docs/assets/images/create-script.png b/docs/assets/images/create-script.png
new file mode 100644
index 00000000..a0481ef0
Binary files /dev/null and b/docs/assets/images/create-script.png differ
diff --git a/docs/assets/images/error-isfoo.png b/docs/assets/images/error-isfoo.png
new file mode 100644
index 00000000..aa33ca6f
Binary files /dev/null and b/docs/assets/images/error-isfoo.png differ
diff --git a/docs/assets/images/error-ispositive-boolean.png b/docs/assets/images/error-ispositive-boolean.png
new file mode 100644
index 00000000..643c4da3
Binary files /dev/null and b/docs/assets/images/error-ispositive-boolean.png differ
diff --git a/docs/assets/images/error-ispositive-string.png b/docs/assets/images/error-ispositive-string.png
new file mode 100644
index 00000000..32cce31b
Binary files /dev/null and b/docs/assets/images/error-ispositive-string.png differ
diff --git a/docs/assets/images/error-ispositive.png b/docs/assets/images/error-ispositive.png
new file mode 100644
index 00000000..183856c3
Binary files /dev/null and b/docs/assets/images/error-ispositive.png differ
diff --git a/docs/compatibility.md b/docs/compatibility.md
index fa19a388..7ecd2c06 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -37,7 +37,7 @@ Since several features were removed from Lua 5.1 for sandboxing reasons, this ta
| `loadfile`, `dofile` | removed for sandboxing, no direct file access |
| `loadstring` bytecode and `string.dump` | exposing bytecode is dangerous for sandboxing reasons |
-Sandboxing challenges are [covered in the dedicated section](sandbox.md).
+Sandboxing challenges are [covered in the dedicated section](sandbox).
## Lua 5.2
+
+
+ 
+
+
+