From 2ffeb5e22a1f827cf76cee19521cd7ad3d253bab Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Wed, 22 Feb 2023 13:31:44 -0500
Subject: [PATCH 01/42] Update external-lua-code.md

---
 docs/external-lua-code.md | 59 ++++++++++++++++++++++++++++++++-------
 1 file changed, 49 insertions(+), 10 deletions(-)

diff --git a/docs/external-lua-code.md b/docs/external-lua-code.md
index ceea3757..6689c6af 100644
--- a/docs/external-lua-code.md
+++ b/docs/external-lua-code.md
@@ -1,14 +1,14 @@
 ---
-title: External Lua Code
+title: External Code
 ---
 
-As of `0.40.0`, tstl supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. You can also include Lua source files directly into your source code.
+In your TSTL project, you might want to import some existing Lua code. Or, you might want to import a library from [npm](https://www.npmjs.com/). This page describes how to use external code.
 
 ## Adding Lua files to your project sources
 
-You can simply add a Lua file as part of your project sources if you add [a declaration file](./advanced/writing-declarations.md) with the same name. You can then simply import the Lua code in your TypeScript.
+The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](./advanced/writing-declarations.md) with the same name. Then, you can then import the Lua code in your TypeScript.
 
-Your project should look like:
+For example, a project might look like this:
 
 ```
 project/
@@ -46,7 +46,7 @@ export function bar(): void;
 
 ## Importing a Lua module that only exports an array
 
-Building on the previous section, you might want also want to import a Lua file that only exports an array. For example, something like:
+Building on the previous section, you might want also want to import a Lua file that exports an array. For example, something like:
 
 ```lua title=things.lua
 return {
@@ -83,10 +83,49 @@ print(things[0].foo); // Prints "123"
 
 For more information about this export syntax, see [the official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require).
 
-## Using NPM packages
+## Importing and creating Lua packages from npm
 
-To use a Lua package, install it via npm and use it as you would for any regular npm package in TypeScript. If the package does not include its own `.d.ts` declaration files, you can create your own by adding a `<package name>.d.ts` [declaration file](./advanced/writing-declarations.md) to your source files.
+TSTL supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. (Most packages on npm contain JavaScript files, but npm allows you to create packages with whatever kinds of files you want.)
 
-:::note
-Including TS or JS files from npm packages is currently NOT supported.
-:::
+### Using Lua packages
+
+To use a Lua package, install it via npm and use it in the same way that you would in a normal TypeScript project. In other words:
+
+```sh
+# If you use npm:
+npm install foo --save
+
+# If you use yarn:
+yarn add foo
+
+# If you use pnpm
+pnpm add foo
+```
+
+And then use it in your code:
+
+```ts
+import { someFunction } from "foo";
+
+someFunction();
+```
+
+Since the npm package was presumably made for TSTL users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for TSTL to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](./advanced/writing-declarations.md).
+
+### Creating Lua packages
+
+Right now, there are not very many Lua/TSTL packages on npm. If you do publish one, put the keywords of "typescript-to-lua", "lua", and "tstl" in your "package.json" file so that the module is searchable.
+
+For an example of a Lua/TSTL package published to npm, see [`isaacscript-common`](https://github.com/IsaacScript/isaacscript/tree/main/packages/isaacscript-common).
+
+## Importing JavaScript or TypeScript packages from npm
+
+**Importing JavaScript or TypeScript packages from npm will not work.** This means that it is impossible to use common JavaScript/TypeScript libraries like [Underscore.js](https://underscorejs.org/) and so on.
+
+(It is not possible for TSTL to work with a generic npm package because most TypeScript libraries only publish the compiled JavaScript to npm. And TSTL can't convert JavaScript to Lua because it needs the type information to create correct code. For example, TSTL needs to be able to distinguish between arrays and objects in order to write the correct index.)
+
+As a workaround, you can copy paste TypeScript code from an npm package directly into your project.
+
+Alternatively, you could fork an existing package and re-publish it as Lua files (instead of JavaScript) so that it can be directly consumed by other TSTL projects. However, doing this kind of thing will only work for really basic packages, since you would have to also fork all of the dependencies and convert those to Lua as well.
+
+Obviously, TSTL programs will not have access to any of the Node.js standard libraries or APIs (like e.g. `import path from "path";`, so make sure that any code that you integrate into your project is not Node-specific.

From 1f5471e44de791018f1080064e84089d5de12d80 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Wed, 22 Feb 2023 13:34:39 -0500
Subject: [PATCH 02/42] rename page

---
 docs/{external-lua-code.md => external-code.md} | 2 +-
 sidebars.json                                   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
 rename docs/{external-lua-code.md => external-code.md} (99%)

diff --git a/docs/external-lua-code.md b/docs/external-code.md
similarity index 99%
rename from docs/external-lua-code.md
rename to docs/external-code.md
index 6689c6af..33899714 100644
--- a/docs/external-lua-code.md
+++ b/docs/external-code.md
@@ -10,7 +10,7 @@ The most straightforward way to add Lua code is to put the Lua file directly nex
 
 For example, a project might look like this:
 
-```
+```text
 project/
 ├── main.ts
 ├── someLua.lua
diff --git a/sidebars.json b/sidebars.json
index 21559104..d6f0b6bc 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -4,7 +4,7 @@
         "configuration",
         "caveats",
         "the-self-parameter",
-        "external-lua-code",
+        "external-code",
         "publishing-modules",
         "editor-support",
         "advanced/writing-declarations",

From 3c8095abd3f42c2fbd4bc3cc3c3091e5c0c5784a Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Wed, 22 Feb 2023 13:37:03 -0500
Subject: [PATCH 03/42] Update external-code.md

---
 docs/external-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index 33899714..33e346ef 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -6,7 +6,7 @@ In your TSTL project, you might want to import some existing Lua code. Or, you m
 
 ## Adding Lua files to your project sources
 
-The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](./advanced/writing-declarations.md) with the same name. Then, you can then import the Lua code in your TypeScript.
+The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](./advanced/writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
 
 For example, a project might look like this:
 

From f7a9ac917e86f2f75ac584bab3412f5f9253749e Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Wed, 22 Feb 2023 13:44:55 -0500
Subject: [PATCH 04/42] Update external-code.md

---
 docs/external-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index 33e346ef..5de47f87 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -128,4 +128,4 @@ As a workaround, you can copy paste TypeScript code from an npm package directly
 
 Alternatively, you could fork an existing package and re-publish it as Lua files (instead of JavaScript) so that it can be directly consumed by other TSTL projects. However, doing this kind of thing will only work for really basic packages, since you would have to also fork all of the dependencies and convert those to Lua as well.
 
-Obviously, TSTL programs will not have access to any of the Node.js standard libraries or APIs (like e.g. `import path from "path";`, so make sure that any code that you integrate into your project is not Node-specific.
+Obviously, TSTL programs will not have access to any of the Node.js standard libraries or APIs (like e.g. `import path from "path";`), so make sure that any code that you integrate into your project is not Node-specific.

From 787db19e33c351e8bed7ac2efb687a3f74c54490 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Wed, 22 Feb 2023 22:59:07 -0500
Subject: [PATCH 05/42] Update external-code.md

---
 docs/external-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index 5de47f87..5946b420 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -114,7 +114,7 @@ Since the npm package was presumably made for TSTL users, it will almost certain
 
 ### Creating Lua packages
 
-Right now, there are not very many Lua/TSTL packages on npm. If you do publish one, put the keywords of "typescript-to-lua", "lua", and "tstl" in your "package.json" file so that the module is searchable.
+Right now, there are not very many Lua/TSTL packages on npm. If you do publish one, put the keywords of "typescript-to-lua", "lua", and "tstl" in your "package.json" file so that the package is searchable.
 
 For an example of a Lua/TSTL package published to npm, see [`isaacscript-common`](https://github.com/IsaacScript/isaacscript/tree/main/packages/isaacscript-common).
 

From 8a3f8ac99f290e6111bd01a75ee38ec45221f1fe Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 17:02:31 -0500
Subject: [PATCH 06/42] Update external-code.md

---
 docs/external-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index 5946b420..bb3d1c09 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -83,7 +83,7 @@ print(things[0].foo); // Prints "123"
 
 For more information about this export syntax, see [the official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require).
 
-## Importing and creating Lua packages from npm
+## Importing Lua packages from npm
 
 TSTL supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. (Most packages on npm contain JavaScript files, but npm allows you to create packages with whatever kinds of files you want.)
 

From 4a42f83b5c6f37fc78ee6d0717afe44a6955d274 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 17:03:15 -0500
Subject: [PATCH 07/42] Update docs/external-code.md

Co-authored-by: Perry van Wesel <Perryvw@users.noreply.github.com>
---
 docs/external-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index bb3d1c09..fc8d9186 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -124,7 +124,7 @@ For an example of a Lua/TSTL package published to npm, see [`isaacscript-common`
 
 (It is not possible for TSTL to work with a generic npm package because most TypeScript libraries only publish the compiled JavaScript to npm. And TSTL can't convert JavaScript to Lua because it needs the type information to create correct code. For example, TSTL needs to be able to distinguish between arrays and objects in order to write the correct index.)
 
-As a workaround, you can copy paste TypeScript code from an npm package directly into your project.
+As a workaround, you can copy paste TypeScript code from a package repository into your project, such that it will be included in the TSTL build.
 
 Alternatively, you could fork an existing package and re-publish it as Lua files (instead of JavaScript) so that it can be directly consumed by other TSTL projects. However, doing this kind of thing will only work for really basic packages, since you would have to also fork all of the dependencies and convert those to Lua as well.
 

From 539815b36f8159efc3ac7dd8fc834659260273d6 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 17:04:40 -0500
Subject: [PATCH 08/42] Update external-code.md

---
 docs/external-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index fc8d9186..0792e299 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -124,7 +124,7 @@ For an example of a Lua/TSTL package published to npm, see [`isaacscript-common`
 
 (It is not possible for TSTL to work with a generic npm package because most TypeScript libraries only publish the compiled JavaScript to npm. And TSTL can't convert JavaScript to Lua because it needs the type information to create correct code. For example, TSTL needs to be able to distinguish between arrays and objects in order to write the correct index.)
 
-As a workaround, you can copy paste TypeScript code from a package repository into your project, such that it will be included in the TSTL build.
+As a workaround, you can copy paste TypeScript code from a package repository directly into your project. (That way, it will be compiled by TSTL alongside your normal code.)
 
 Alternatively, you could fork an existing package and re-publish it as Lua files (instead of JavaScript) so that it can be directly consumed by other TSTL projects. However, doing this kind of thing will only work for really basic packages, since you would have to also fork all of the dependencies and convert those to Lua as well.
 

From 50fb84abebaedd843d04557605dbcaadf7f96b04 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 17:08:19 -0500
Subject: [PATCH 09/42] Update external-code.md

---
 docs/external-code.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/external-code.md b/docs/external-code.md
index 0792e299..d605d00c 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -83,6 +83,10 @@ print(things[0].foo); // Prints "123"
 
 For more information about this export syntax, see [the official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require).
 
+## Importing a type definitions package from npm
+
+TODO
+
 ## Importing Lua packages from npm
 
 TSTL supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. (Most packages on npm contain JavaScript files, but npm allows you to create packages with whatever kinds of files you want.)
@@ -112,6 +116,10 @@ someFunction();
 
 Since the npm package was presumably made for TSTL users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for TSTL to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](./advanced/writing-declarations.md).
 
+### Creating type definition packages
+
+
+
 ### Creating Lua packages
 
 Right now, there are not very many Lua/TSTL packages on npm. If you do publish one, put the keywords of "typescript-to-lua", "lua", and "tstl" in your "package.json" file so that the package is searchable.

From 5b87da73258edd167d59df1a6320ad349f2c0080 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:02:29 -0500
Subject: [PATCH 10/42] feat: adding more info

---
 docs/external-code.md                         |  32 ++---
 docs/getting-started.md                       | 111 ++++++++++++++----
 docs/publishing-modules.md                    |  95 +++++++--------
 ...g-declarations.md => type-declarations.md} |  18 ++-
 sidebars.json                                 |   2 +-
 src/pages/index.tsx                           |   4 +-
 6 files changed, 158 insertions(+), 104 deletions(-)
 rename docs/{advanced/writing-declarations.md => type-declarations.md} (93%)

diff --git a/docs/external-code.md b/docs/external-code.md
index d605d00c..53695fd6 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -2,7 +2,11 @@
 title: External Code
 ---
 
-In your TSTL project, you might want to import some existing Lua code. Or, you might want to import a library from [npm](https://www.npmjs.com/). This page describes how to use external code.
+In your `tstl` project, you might want to import some existing Lua code. Or, you might want to import a library from [npm](https://www.npmjs.com/). This page describes how to use external code.
+
+:::note
+This page is about importing code that **actually executes something**. In a `tstl` project, it is common to depend on external library that provide type declarations. Type declaration libraries only provide types: they do not contribute any code to your actual program output. Thus, they work a little differently from what is discussed on this page. For information on how type declarations work, see the [type declarations page](type-declarations.md).
+:::
 
 ## Adding Lua files to your project sources
 
@@ -83,13 +87,9 @@ print(things[0].foo); // Prints "123"
 
 For more information about this export syntax, see [the official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require).
 
-## Importing a type definitions package from npm
-
-TODO
-
 ## Importing Lua packages from npm
 
-TSTL supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. (Most packages on npm contain JavaScript files, but npm allows you to create packages with whatever kinds of files you want.)
+`tstl` supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. (Most packages on npm contain JavaScript files, but npm allows you to create packages with whatever kinds of files you want.)
 
 ### Using Lua packages
 
@@ -102,7 +102,7 @@ npm install foo --save
 # If you use yarn:
 yarn add foo
 
-# If you use pnpm
+# If you use pnpm:
 pnpm add foo
 ```
 
@@ -114,26 +114,20 @@ import { someFunction } from "foo";
 someFunction();
 ```
 
-Since the npm package was presumably made for TSTL users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for TSTL to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](./advanced/writing-declarations.md).
-
-### Creating type definition packages
-
-
+Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](./advanced/writing-declarations.md).
 
 ### Creating Lua packages
 
-Right now, there are not very many Lua/TSTL packages on npm. If you do publish one, put the keywords of "typescript-to-lua", "lua", and "tstl" in your "package.json" file so that the package is searchable.
-
-For an example of a Lua/TSTL package published to npm, see [`isaacscript-common`](https://github.com/IsaacScript/isaacscript/tree/main/packages/isaacscript-common).
+For more information on creating a Lua package yourself, see [the page on publishing modules](publishing-modules.md).
 
 ## Importing JavaScript or TypeScript packages from npm
 
 **Importing JavaScript or TypeScript packages from npm will not work.** This means that it is impossible to use common JavaScript/TypeScript libraries like [Underscore.js](https://underscorejs.org/) and so on.
 
-(It is not possible for TSTL to work with a generic npm package because most TypeScript libraries only publish the compiled JavaScript to npm. And TSTL can't convert JavaScript to Lua because it needs the type information to create correct code. For example, TSTL needs to be able to distinguish between arrays and objects in order to write the correct index.)
+(It is not possible for `tstl` to work with a generic npm package because most TypeScript libraries only publish the compiled JavaScript to npm. And `tstl` can't convert JavaScript to Lua because it needs the type information to create correct code. For example, `tstl` needs to be able to distinguish between arrays and objects in order to write the correct index.)
 
-As a workaround, you can copy paste TypeScript code from a package repository directly into your project. (That way, it will be compiled by TSTL alongside your normal code.)
+As a workaround, you can copy paste TypeScript code from a package repository directly into your project. (That way, it will be compiled by `tstl` alongside your normal code.)
 
-Alternatively, you could fork an existing package and re-publish it as Lua files (instead of JavaScript) so that it can be directly consumed by other TSTL projects. However, doing this kind of thing will only work for really basic packages, since you would have to also fork all of the dependencies and convert those to Lua as well.
+Alternatively, you could fork an existing package and re-publish it as Lua files (instead of JavaScript) so that it can be directly consumed by other `tstl` projects. However, doing this kind of thing will only work for really basic packages, since you would have to also fork all of the dependencies and convert those to Lua as well.
 
-Obviously, TSTL programs will not have access to any of the Node.js standard libraries or APIs (like e.g. `import path from "path";`), so make sure that any code that you integrate into your project is not Node-specific.
+Obviously, `tstl` programs will not have access to any of the Node.js standard libraries or APIs (like e.g. `import path from "path";`), so make sure that any code that you integrate into your project is not Node-specific.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 87334e50..bc058679 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -2,32 +2,44 @@
 title: Getting Started
 ---
 
-This is a quick introduction into project setup and our CLI. For a TypeScript quick start please read: https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html
+Are you ready to start a TypeScript project that will be automatically converted to Lua? This page will help you get started.
+
+Note that we assume that you are already familiar with how TypeScript works. If you have never coded a project in TypeScript before, or you need a refresher, first read the [official TypeScript tutorial](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html).
 
 ## Installation
 
-TypeScriptToLua is built using [Node.js](https://nodejs.org/) and distributed via [npm](https://www.npmjs.com/). To install it, you need to create a `package.json` file in the root of your project, containing at least `{}`. Then you can use this command to add the latest version of TypeScriptToLua to your project:
+TypeScriptToLua is built using [Node.js](https://nodejs.org/) and distributed via [npm](https://www.npmjs.com/). To install it, you need to create a `package.json` file in the root of your project, containing at least `{}`. Then, you can add the latest version of TypeScriptToLua to your project:
 
 ```bash
-npm install -D typescript-to-lua
+# If you use npm:
+npm install --save-dev typescript-to-lua
+
+# If you use yarn:
+yarn add --dev typescript-to-lua
+
+# If you use pnpm:
+pnpm add --save-dev typescript-to-lua
 ```
 
+(If you don't know the difference between the package managers, choose `npm`.)
+
 :::note
-Installing `tstl` locally is recommended to keep your build reproducible and prevent version conflicts between projects. However, it is also possible to install it globally with `npm install --global typescript-to-lua` or run it without install using `npx typescript-to-lua`.
+Installing `tstl` locally is recommended to keep your build reproducible and prevent version conflicts between projects. However, it is also possible to install it globally with `npm install --global typescript-to-lua`.
 :::
 
 ## Project setup
 
-TypeScriptToLua shares the configuration format with vanilla TypeScript. This file is called `tsconfig.json` and should be located in your project's root.
+TypeScriptToLua is configured using a `tsconfig.json` file. (This is the same file used to configure vanilla TypeScript.) It should be located in your project's root.
 
-Basic recommended configuration:
+### Basic Configuration
 
 ```json title=tsconfig.json
 {
+  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json",
   "compilerOptions": {
-    "target": "esnext",
-    "lib": ["esnext"],
-    "moduleResolution": "node",
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "Node",
     "types": [],
     "strict": true
   },
@@ -37,13 +49,48 @@ Basic recommended configuration:
 }
 ```
 
-Check out [Configuration](configuration.md) page for more information.
+If your target Lua environment is not [LuaJIT](https://luajit.org/), make sure to change the value of `luaTarget`. Valid values are `JIT`, `5.3`, `5.2`, `5.1`, `5.0`, and `universal`.
+
+:::note
+You can find out the version of your Lua environment by running: `print(_VERSION)`
+:::
+
+Check out [configuration page](configuration.md) for more information.
+
+### Strictest Configuration
+
+If you want the TypeScript compiler to be as strict as possible, then you need to enable some additional flags. Handily, we can extend from [the "strictest" TypeScript community config](https://github.com/tsconfig/bases/blob/main/bases/strictest.json) to abstract this away. Adding this to top of your `tsconfig.json` file:
+
+```json
+  // We extend the strictest base config:
+  // https://github.com/tsconfig/bases/blob/main/bases/strictest.json
+  "extends": "@tsconfig/strictest/tsconfig.json",
+```
 
 ## Building your project
 
-Our command line interface is called `tstl` and it works almost exactly as TypeScript's `tsc`.
+Our command line interface is called `tstl` and it works almost exactly the same as TypeScript's `tsc`.
 
-Since `tstl` is installed locally to your project, you cannot run it as a bare command in your terminal, so it's recommended to use it with [npm scripts](https://docs.npmjs.com/misc/scripts).
+Since `tstl` is installed locally to your project, you cannot run it as a bare command in your terminal. Instead, use:
+
+```bash
+# If you use npm:
+npx tstl
+
+# If you use yarn (yarn also uses npx):
+npx tstl
+
+# If you use pnpm:
+pnpm exec tstl
+```
+
+:::note
+The binary is installed to `node_modules/.bin/tstl`, so you can also run it directly from that path if needed. (But this is not recommended.)
+:::
+
+### npm scripts
+
+You can also run `tstl` as an [npm script](https://docs.npmjs.com/misc/scripts). Using npm scripts for this sort of thing is idiomatic in JavaScript/TypeScript projects. This is accomplished by adding a `scripts` field to the `package.json` file:
 
 ```json title=package.json
 {
@@ -58,6 +105,8 @@ Since `tstl` is installed locally to your project, you cannot run it as a bare c
 }
 ```
 
+Then, you can run the script like this:
+
 ```bash
 # Build
 npm run build
@@ -66,21 +115,33 @@ npm run build
 npm run dev
 ```
 
-:::note
-For testing purposes you also can run `tstl` directly from your terminal with `node_modules/.bin/tstl` or `npx tstl`.
-:::
+## Type Declarations
+
+Using TypeScript instead of Lua is useful because everything plugs together in a verifiable way. With that in mind, `tstl` is not very useful unless you pair it with type declarations for your particular Lua environment. That way, TypeScript can catch the typos when you call some API function or use some API variable.
+
+For instructions on how to install type declaration packages, see the page on [type declarations](type-declarations.md).
 
-## Declarations
+### Type Declaration Packages - Official
 
-The real power of this transpiler is usage together with good declarations for the Lua API provided. Some examples of Lua interface declarations can be found here:
+We provide an official type declaration package for [the Lua standard library](https://github.com/TypeScriptToLua/lua-types).
+
+These declarations do not come with `tstl` by default because most of the time, you should not be using the Lua standard library directly. In other words, you can just write idiomatic TypeScript and `tstl` will convert things properly. (For example, it converts `Math.round` to `math.round`.) However, if you want to do some low-level Lua stuff and work with the Lua standard library, then you will need to install these type declarations so that the TypeScript compiler can understand what you are doing.
+
+### Type Declaration Packages - Unofficial
+
+Type declarations exist for some common Lua environments:
+
+- [Defold Game Engine](https://github.com/ts-defold/types)
+- [LÖVE 2D Game Engine](https://github.com/hazzard993/love-typescript-definitions)
+
+Additionally, type declarations exist for some games:
 
-- [Lua Standard Library](https://github.com/TypeScriptToLua/lua-types)
-- [Dota 2 Custom Games](https://github.com/ModDota/API/tree/master/declarations/server) ([template](https://github.com/ModDota/TypeScriptAddonTemplate))
-- [Defold Game Engine Scripting](https://github.com/ts-defold/types)
-- [LÖVE 2D Game Development](https://github.com/hazzard993/love-typescript-definitions)
-- [World of Warcraft - Addon Development](https://github.com/wartoshika/wow-declarations)
-- [World of Warcraft Classic - Addon Development](https://github.com/wartoshika/wow-classic-declarations)
-- [Typed Factorio](https://github.com/GlassBricks/typed-factorio)
 - [The Binding of Isaac: Rebirth](https://isaacscript.github.io)
-- [Retro Gadget](https://github.com/DarkMio/retro-gadgets-typedefs) ([template](https://github.com/DarkMio/retro-gadgets-template))
+- [Dota 2](https://github.com/ModDota/API/tree/master/declarations/server) ([template](https://github.com/ModDota/TypeScriptAddonTemplate))
+- [Factorio](https://github.com/GlassBricks/typed-factorio)
 - [Garry's Mod](https://github.com/lolleko/gmod-typescript)
+- [Retro Gadget](https://github.com/DarkMio/retro-gadgets-typedefs) ([template](https://github.com/DarkMio/retro-gadgets-template))
+- [World of Warcraft](https://github.com/wartoshika/wow-declarations)
+- [World of Warcraft Classic](https://github.com/wartoshika/wow-classic-declarations)
+
+(If you have created type declarations for a new game, you can click on the "Edit this page" link below to add it to the list.)
diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index 807f314e..b9ac1941 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -2,16 +2,22 @@
 title: Publishing Modules
 ---
 
-As of `0.40.0`, tstl supports module resolution for libraries, which means you can _use_ and _create_ npm packages containing `.lua` files. You can also include Lua source files directly into your source code.
+There are three kinds of `tstl` libraries published on npm:
 
-- You cannot import `.ts` and `.tsx` source files
-- You must use `"buildMode": "library"`
-- It is recommended you use `"declaration": true`
-- You cannot use `"luaBundle"` in packages intended to be included as dependency in another project
+- **Type declaration libraries** - Provides only _ambient_ types. In other words, these libraries do not contain any code which can be executed.
+- **Lua libraries** - Provides Lua code that can be imported and executed by `tstl` projects.
+- **Mixed** - Provides **both** type declarations and Lua code at the same time. (These kinds of libraries are less common.)
+
+This page describes how to create a Lua package and publish it to npm.
+
+## Basic Limitations
+
+- You cannot import `.ts` and `.tsx` source files.
+- You cannot use `"luaBundle"` in packages intended to be included as dependency in another project.
 
 ## Project Configuration
 
-Your `tsconfig.json` file must at least specify the following...
+Your `tsconfig.json` file must include the following fields:
 
 ```json title=tsconfig.json
 {
@@ -24,65 +30,60 @@ Your `tsconfig.json` file must at least specify the following...
 }
 ```
 
-And your `package.json` file should specify the `types` property. You should also specify the `main` property if your module contains runnable Lua code.
+Your `package.json` file should include:
 
 ```json title=package.json
 {
-  "main": "./dist/index", // points to ./dist/index.lua
-  "types": "./dist/index" // points to ./dist/index.d.ts
-}
-```
-
-These must be **relative** paths within your module **without** the file's extension.
-
-> These are set to `"index"` by default so if you _really_ don't want to specify these you can keep an `index.d.ts` and `index.lua` file at the top level of your package.
-
-## Publishing
-
-Within your `package.json` you can specify the `files` field to mark what files to publish.
+  "name": "foo",
+  "version": "1.0.0",
+  "description": "A description of your package.",
+  "keywords": ["typescript-to-lua", "lua", "tstl"],
+  "homepage": "https://github.com/AUTHOR_NAME/PROJECT_NAME",
+  "bugs": {
+    "url": "https://github.com/AUTHOR_NAME/PROJECT_NAME/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AUTHOR_NAME/PROJECT_NAME.git"
+  },
+  "license": "GPL-3.0",
+  "author": "AUTHOR_NAME",
+  "files": ["dist", "LICENSE", "package.json", "README.md"],
 
-This is useful if you don't want to publish your source code.
+  // Only specify this if your library is a type declaration library.
+  "types": "./dist/index.d.ts",
 
-```json title=package.json
-{
-  "files": [
-    "dist/**/*.lua", // publish all Lua files in /dist/
-    "dist/**/*.d.ts" // publish all declaration files in /dist/
-  ]
+  // Only specify this if your library is a Lua library.
+  // (Do NOT include the file extension here, or things will not work properly.)
+  "main": "./dist/index", 
 }
 ```
 
-You can use `npm publish --dry-run` to see what files would be published without publishing your package.
-
-- Some files will always be published e.g. `package.json`, `README.md`.
-- Modules specified in `"devDependencies"` will not be available to the module at runtime.
-- The `tsconfig.json` file does nothing for users of your module.
-
-And when you're happy, your `package.json` has a `name`, `version`, `description`, and you are logged into NPM on your machine... you can run `npm publish` to publish your module.
+## Publishing
 
-## Using the Module
+The `files` field in the `package.json` file dictates which specific files will be uploaded to npm.
 
-Assuming the module is available on NPM, users of your module can download it like so.
+Note that:
 
-```bash
-npm install <package-name>
-# OR
-yarn add <package-name>
-```
+- Regardless of the contents of the `files` field, some files will always be published, like `package.json` and `README.md`.
+- Modules specified in `"devDependencies"` will not be available to the module at runtime.
+- There is no need to publish the `tsconfig.json` file, as it will do nothing for the users of your module.
 
-Now they can start using it.
+When you are ready to publish:
 
-```ts title=example.ts
-import { func } from "<package-name>";
+- Use `npm login` to cache your npm credentials.
+- Use `npm publish --dry-run` to see what files would be published without actually uploading anything.
+- Use `npm publish` to actually upload it.
 
-func();
-```
+## Using the Module
 
-TypeScriptToLua will handle the module resolution from here.
+See [the page on using Lua packages](external-code.md#using-lua-packages).
 
 ## Example projects
 
-For example projects using external Lua, you can look at the projects used in the TypeScriptToLua tests:
+For an example of a Lua package published to npm, see [`isaacscript-common`](https://github.com/IsaacScript/isaacscript/tree/main/packages/isaacscript-common).
+
+You can also reference the projects used in the TypeScriptToLua tests:
 
 ### [A project using Lua from node_modules packages](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules)
 
diff --git a/docs/advanced/writing-declarations.md b/docs/type-declarations.md
similarity index 93%
rename from docs/advanced/writing-declarations.md
rename to docs/type-declarations.md
index 360d1cd3..b2590ae4 100644
--- a/docs/advanced/writing-declarations.md
+++ b/docs/type-declarations.md
@@ -1,20 +1,18 @@
 ---
-title: Writing Declarations
+title: Type Declarations
 ---
 
-The real power of the transpiler is unlocked when combining it with declarations for your target environment. Declarations tell TypeScript which Lua API is available in your target context.
+Using TypeScript instead of Lua is useful because everything plugs together in a verifiable way. With that in mind, `tstl` is not very useful unless you pair it with type declarations for your particular Lua environment. That way, TypeScript can catch the typos when you call some API function or use some API variable.
 
-If you need tips or help writing declarations, feel free to [join our Discord](https://discord.gg/BWAq58Y).
+If you need help writing declarations, feel free to [join our Discord server](https://discord.gg/BWAq58Y).
 
 ## About Declaration Files
 
-Declaration files end with the extension _.d.ts_. These contain pure ambient code.
+Declaration files end with the extension `.d.ts` (which stands for "declaration TypeScript file"). Declaration files are different from normal `.ts` files in that they must only contain _ambient_ code. In the context of TypeScript, _ambient_ refers to code that is wiped away by the compiler and not emitted into the actual program output.
 
-For TypeScriptToLua, these files should contain information that describes the target Lua environment.
+In other words, anything you put into a `.d.ts` file will inform the TypeScript compiler about what the format of something is. And it will never appear in the generated `.lua` file.
 
-This means functions, modules, variables and other members of the target Lua environment are primarily described in these files.
-
-They don't contain code that you would execute. Similar to how you'd write an interface in some other languages. TypeScriptToLua doesn't output any information from these files either.
+For TypeScriptToLua, these files should contain information that describes the target Lua environment. This means functions, modules, variables and other members of the target Lua environment are primarily described in these files.
 
 :::note
 You can write ambient declarations inside _.ts_ files as well.
@@ -38,7 +36,7 @@ declare const _VERSION: number;
 
 /**
  * Receives any number of arguments, and prints their values to stdout, using the
- * tostring function to convert them to strings. print is not intended for
+ * `tostring` function to convert them to strings. print is not intended for
  * formatted output, but only as a quick way to show a value, typically for
  * debugging. For formatted output, use string.format.
  * @param args Arguments to print
@@ -555,7 +553,7 @@ declare module "mymodule" {
 }
 ```
 
-## NPM Publishing
+## npm Publishing
 
 It is possible to publish a list of declarations for other users to easily download via [npm](https://www.npmjs.com/).
 
diff --git a/sidebars.json b/sidebars.json
index d6f0b6bc..9a0fa175 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -3,11 +3,11 @@
         "getting-started",
         "configuration",
         "caveats",
+        "type-declarations",
         "the-self-parameter",
         "external-code",
         "publishing-modules",
         "editor-support",
-        "advanced/writing-declarations",
         "advanced/compiler-annotations",
         "advanced/language-extensions",
         "json-modules",
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index 503f997a..f90f63c2 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -140,7 +140,7 @@ export default function Home() {
                         <div className={`col`}>
                             <h1>Getting started</h1>
                             <p>
-                                Getting started with <b>TSTL</b> is easy, simply install typescript-to-lua from npm:
+                                Getting started with <b>TSTL</b> is easy. Simply install `typescript-to-lua` from npm:
                             </p>
                             <CodeBlock>$ npm install -D typescript typescript-to-lua</CodeBlock>
                             <p>
@@ -149,7 +149,7 @@ export default function Home() {
                             <CodeBlock>$ npx tstl</CodeBlock>
                             <p>
                                 For more information, see{" "}
-                                <a href={useBaseUrl("docs/getting-started")}>tstl Getting Started documentation</a>.
+                                <a href={useBaseUrl("docs/getting-started")}>the getting started page</a>.
                             </p>
                         </div>
                     </div>

From 1d00161952c0458e025f7791692add5ed094b5ce Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:04:14 -0500
Subject: [PATCH 11/42] fix: prettier

---
 docs/publishing-modules.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index b9ac1941..0c7f6145 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -55,7 +55,7 @@ Your `package.json` file should include:
 
   // Only specify this if your library is a Lua library.
   // (Do NOT include the file extension here, or things will not work properly.)
-  "main": "./dist/index", 
+  "main": "./dist/index"
 }
 ```
 

From 953485c9fe10e9b283de8ce66d1f355c31e860ba Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:07:02 -0500
Subject: [PATCH 12/42] Update getting-started.md

---
 docs/getting-started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index bc058679..30fddb74 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -59,7 +59,7 @@ Check out [configuration page](configuration.md) for more information.
 
 ### Strictest Configuration
 
-If you want the TypeScript compiler to be as strict as possible, then you need to enable some additional flags. Handily, we can extend from [the "strictest" TypeScript community config](https://github.com/tsconfig/bases/blob/main/bases/strictest.json) to abstract this away. Adding this to top of your `tsconfig.json` file:
+If you want the TypeScript compiler to be as strict as possible, then you need to enable some additional flags. Handily, we can extend from [the "strictest" TypeScript community config](https://github.com/tsconfig/bases/blob/main/bases/strictest.json) to abstract this away by adding this to top of the `tsconfig.json` file:
 
 ```json
   // We extend the strictest base config:

From 1fea1c1e959931fdaa39582e5f648ce0751d2e8c Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:11:48 -0500
Subject: [PATCH 13/42] better instructions for installing type declarations

---
 docs/getting-started.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 30fddb74..5f7e1b64 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -119,7 +119,15 @@ npm run dev
 
 Using TypeScript instead of Lua is useful because everything plugs together in a verifiable way. With that in mind, `tstl` is not very useful unless you pair it with type declarations for your particular Lua environment. That way, TypeScript can catch the typos when you call some API function or use some API variable.
 
-For instructions on how to install type declaration packages, see the page on [type declarations](type-declarations.md).
+For instructions on how to install type declaration packages, see the readme file for the individual package in question. In short, you need to install the package from npm, and then add the following to your `tsconfig.json` file:
+
+```json title=tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["foo"],
+  }
+}
+```
 
 ### Type Declaration Packages - Official
 

From 07acebc0c8fdd3f07f4bcf67b89c9d1940cee9fb Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:14:48 -0500
Subject: [PATCH 14/42] more edits

---
 docs/publishing-modules.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index 0c7f6145..5022ccdb 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -30,7 +30,7 @@ Your `tsconfig.json` file must include the following fields:
 }
 ```
 
-Your `package.json` file should include:
+Your `package.json` file should include the following fields:
 
 ```json title=package.json
 {
@@ -46,19 +46,19 @@ Your `package.json` file should include:
     "type": "git",
     "url": "git+https://github.com/AUTHOR_NAME/PROJECT_NAME.git"
   },
-  "license": "GPL-3.0",
+  "license": "MIT",
   "author": "AUTHOR_NAME",
   "files": ["dist", "LICENSE", "package.json", "README.md"],
-
-  // Only specify this if your library is a type declaration library.
+  // Only specify "types" if your library is a type declaration library.
   "types": "./dist/index.d.ts",
-
-  // Only specify this if your library is a Lua library.
+  // Only specify "main" if your library is a Lua library.
   // (Do NOT include the file extension here, or things will not work properly.)
   "main": "./dist/index"
 }
 ```
 
+(Change `AUTHOR_NAME`, `PROJECT_NAME`, and the license accordingly.)
+
 ## Publishing
 
 The `files` field in the `package.json` file dictates which specific files will be uploaded to npm.

From 434f2cc95c7ace21f118dea8857740946a3282d0 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:16:28 -0500
Subject: [PATCH 15/42] fix

---
 docs/type-declarations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/type-declarations.md b/docs/type-declarations.md
index b2590ae4..e1b4d7c7 100644
--- a/docs/type-declarations.md
+++ b/docs/type-declarations.md
@@ -10,7 +10,7 @@ If you need help writing declarations, feel free to [join our Discord server](ht
 
 Declaration files end with the extension `.d.ts` (which stands for "declaration TypeScript file"). Declaration files are different from normal `.ts` files in that they must only contain _ambient_ code. In the context of TypeScript, _ambient_ refers to code that is wiped away by the compiler and not emitted into the actual program output.
 
-In other words, anything you put into a `.d.ts` file will inform the TypeScript compiler about what the format of something is. And it will never appear in the generated `.lua` file.
+In other words, anything you put into a `.d.ts` file will inform the TypeScript compiler about what the format of something is. And it will never appear in the generated `.lua` file(s).
 
 For TypeScriptToLua, these files should contain information that describes the target Lua environment. This means functions, modules, variables and other members of the target Lua environment are primarily described in these files.
 

From 064a6d74f2e8196e62e8694017e05f0741408644 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:17:17 -0500
Subject: [PATCH 16/42] fix

---
 src/pages/index.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index f90f63c2..2c4ca428 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -140,7 +140,7 @@ export default function Home() {
                         <div className={`col`}>
                             <h1>Getting started</h1>
                             <p>
-                                Getting started with <b>TSTL</b> is easy. Simply install `typescript-to-lua` from npm:
+                                Getting started with <b>TSTL</b> is easy. Simply install "typescript-to-lua" from npm:
                             </p>
                             <CodeBlock>$ npm install -D typescript typescript-to-lua</CodeBlock>
                             <p>

From a3cc8f039adc79d6a481baebf082f5bd4fe46969 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:20:46 -0500
Subject: [PATCH 17/42] fix: link

---
 docs/type-declarations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/type-declarations.md b/docs/type-declarations.md
index e1b4d7c7..012b5037 100644
--- a/docs/type-declarations.md
+++ b/docs/type-declarations.md
@@ -118,7 +118,7 @@ This allows users to modify `this` inside a function and expect behaviour simila
 
 But obviously Lua does not have a `self` parameter for every function, so one of the three options must happen to tell TypeScriptToLua there is no "contextual parameter" (`self`):
 
-1. Use `this: void` as the first parameter of the function / method. This formally describes to TypeScript to not allow `this` to be modified inside this function. (you could also use the [noImplicitThis](../configuration.md#custom-options) option to disallow `this` to be modified if `this` is of an `any` type).
+1. Use `this: void` as the first parameter of the function / method. This formally describes to TypeScript to not allow `this` to be modified inside this function. (you could also use the [noImplicitThis](configuration.md#custom-options) option to disallow `this` to be modified if `this` is of an `any` type).
 2. Use `@noSelf` in the comments of the declaration's owner (the namespace, module, object, etc).
 3. Use `@noSelfInFile` at the beginning of the file in a comment to make sure every function defined in this file does not use a "contextual parameter".
 

From 0eb801db810c49574b7dec128136564854ad0dd3 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:30:45 -0500
Subject: [PATCH 18/42] fix: links

---
 docs/external-code.md     | 4 ++--
 docs/type-declarations.md | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index 53695fd6..daaf6b58 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -10,7 +10,7 @@ This page is about importing code that **actually executes something**. In a `ts
 
 ## Adding Lua files to your project sources
 
-The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](./advanced/writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
+The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
 
 For example, a project might look like this:
 
@@ -114,7 +114,7 @@ import { someFunction } from "foo";
 someFunction();
 ```
 
-Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](./advanced/writing-declarations.md).
+Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](writing-declarations.md).
 
 ### Creating Lua packages
 
diff --git a/docs/type-declarations.md b/docs/type-declarations.md
index 012b5037..b235e834 100644
--- a/docs/type-declarations.md
+++ b/docs/type-declarations.md
@@ -170,7 +170,7 @@ Here are some commonly used TSDoc tags used in comments:
 | `@param <name> <description>` | Defines a parameter. e.g. A parameter for a function |
 | `@return <description>`       | Describes the return value of a function / method    |
 
-TypeScriptToLua takes this further. Some "tags" change how the transpiler translates certain pieces of code. These are referred to as [annotations](compiler-annotations.md).
+TypeScriptToLua takes this further. Some "tags" change how the transpiler translates certain pieces of code. These are referred to as [annotations](advanced/compiler-annotations.md).
 
 As an example, `@tupleReturn` marks a function as something which returns multiple values instead of its array.
 
@@ -195,7 +195,7 @@ let [c, d] = array();
 // local c, d = unpack(array())
 ```
 
-See [Compiler Annotations](compiler-annotations.md) page for more information.
+See [Compiler Annotations](advanced/compiler-annotations.md) page for more information.
 
 ## Environmental Declarations
 
@@ -530,7 +530,7 @@ const v3 = (v1 * 4) as Vector;
 const d = v3.dot(v2);
 ```
 
-The second option was added in version [0.38.0](https://github.com/TypeScriptToLua/TypeScriptToLua/blob/master/CHANGELOG.md#0380). You can now use [language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions) that allow declaring special functions which will transpile to operators. This will be completely type safe if the operators are declared correctly. See [Operator Map Types](language-extensions.md#operator-map-types) for more information.
+The second option was added in version [0.38.0](https://github.com/TypeScriptToLua/TypeScriptToLua/blob/master/CHANGELOG.md#0380). You can now use [language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions) that allow declaring special functions which will transpile to operators. This will be completely type safe if the operators are declared correctly. See [Operator Map Types](advanced/language-extensions.md#operator-map-types) for more information.
 
 ### Import and export
 

From 05b41d6155bb81f26af85aae2968992ea4bba1a0 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:35:32 -0500
Subject: [PATCH 19/42] fix: link

---
 docs/external-code.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/external-code.md b/docs/external-code.md
index daaf6b58..5847cc31 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -10,7 +10,7 @@ This page is about importing code that **actually executes something**. In a `ts
 
 ## Adding Lua files to your project sources
 
-The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
+The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](type-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
 
 For example, a project might look like this:
 
@@ -114,7 +114,7 @@ import { someFunction } from "foo";
 someFunction();
 ```
 
-Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](writing-declarations.md).
+Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](type-declarations.md).
 
 ### Creating Lua packages
 

From 683e1c0dbf327f9f675cc2caaf2a246aa9943697 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 19:53:23 -0500
Subject: [PATCH 20/42] fix: link

---
 docusaurus.config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docusaurus.config.js b/docusaurus.config.js
index 006e31fb..c5343f7e 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -53,7 +53,7 @@ module.exports = {
                         },
                         {
                             label: "Advanced",
-                            to: "docs/advanced/writing-declarations",
+                            to: "docs/advanced/type-declarations",
                         },
                     ],
                 },

From 5e4e13fadb42d5b5d7949d9ac69f15d2491caaeb Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 20:00:52 -0500
Subject: [PATCH 21/42] fix: lint

---
 docs/getting-started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 5f7e1b64..47843c36 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -124,7 +124,7 @@ For instructions on how to install type declaration packages, see the readme fil
 ```json title=tsconfig.json
 {
   "compilerOptions": {
-    "types": ["foo"],
+    "types": ["foo"]
   }
 }
 ```

From 8179823394d08dec8ac17eddef2e4304cbf48418 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Thu, 23 Feb 2023 20:03:49 -0500
Subject: [PATCH 22/42] fix: build

---
 docusaurus.config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docusaurus.config.js b/docusaurus.config.js
index c5343f7e..23b3a0ec 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -53,7 +53,7 @@ module.exports = {
                         },
                         {
                             label: "Advanced",
-                            to: "docs/advanced/type-declarations",
+                            to: "docs/advanced/compiler-annotations",
                         },
                     ],
                 },

From fd665f9ec094c974a1a176ced3d17a92e498517c Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 12:58:11 -0500
Subject: [PATCH 23/42] feat: add sorting caveat

---
 docs/caveats.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/caveats.md b/docs/caveats.md
index 57a731e7..ec8f4f26 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -82,3 +82,14 @@ Even though iterating over object keys with `for ... in` does not guarantee orde
 ### Iterating an array with `for ... in`
 
 Not allowed.
+
+### Sorting
+
+A sorting algorithm is [said to be stable](https://stackoverflow.com/questions/1517793/what-is-stability-in-sorting-algorithms-and-why-is-it-important) if two objects with equal keys appear in the same order in sorted output as they appear in the input array to be sorted.
+
+- Sorting is part of the JavaScript standard library via the `Array.sort` method. It is guaraunteed to be [stable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).
+- Sorting is also part of the Lua standard library via the `table.sort` method. It is **not** guaraunteed to be [stable](https://www.lua.org/manual/5.3/manual.html#pdf-table.sort).
+
+TypeScriptToLua relies on the Lua standard library for sorting. In other words, it transpiles `[1, 2, 3].sort();` to `table.sort({1, 2, 3})`. So beware that your sorts will no longer be stable!
+
+If you need stable sorting, you have to manually use a custom sorting function. For some examples of this, see the [sorting helper functions from `isaacscript-common`](https://github.com/IsaacScript/isaacscript/blob/main/packages/isaacscript-common/src/functions/sort.ts).

From 6e2c348ea00a8c250c3f3fcfa4cbbf2f75b54d3d Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:12:14 -0500
Subject: [PATCH 24/42] fix: no wipe

---
 docs/type-declarations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/type-declarations.md b/docs/type-declarations.md
index b235e834..30bd299d 100644
--- a/docs/type-declarations.md
+++ b/docs/type-declarations.md
@@ -8,7 +8,7 @@ If you need help writing declarations, feel free to [join our Discord server](ht
 
 ## About Declaration Files
 
-Declaration files end with the extension `.d.ts` (which stands for "declaration TypeScript file"). Declaration files are different from normal `.ts` files in that they must only contain _ambient_ code. In the context of TypeScript, _ambient_ refers to code that is wiped away by the compiler and not emitted into the actual program output.
+Declaration files end with the extension `.d.ts` (which stands for "declaration TypeScript file"). Declaration files are different from normal `.ts` files in that they must only contain _ambient_ code. In the context of TypeScript, _ambient_ refers to code that not emitted into the actual program output.
 
 In other words, anything you put into a `.d.ts` file will inform the TypeScript compiler about what the format of something is. And it will never appear in the generated `.lua` file(s).
 

From c2b232f50a5e01819dc44eaa984d0dd6b75ea4dc Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:16:53 -0500
Subject: [PATCH 25/42] rename file

---
 docs/external-code.md                                  | 6 +++---
 docs/{type-declarations.md => writing-declarations.md} | 4 ++--
 sidebars.json                                          | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)
 rename docs/{type-declarations.md => writing-declarations.md} (98%)

diff --git a/docs/external-code.md b/docs/external-code.md
index 5847cc31..17fb03c5 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -5,12 +5,12 @@ title: External Code
 In your `tstl` project, you might want to import some existing Lua code. Or, you might want to import a library from [npm](https://www.npmjs.com/). This page describes how to use external code.
 
 :::note
-This page is about importing code that **actually executes something**. In a `tstl` project, it is common to depend on external library that provide type declarations. Type declaration libraries only provide types: they do not contribute any code to your actual program output. Thus, they work a little differently from what is discussed on this page. For information on how type declarations work, see the [type declarations page](type-declarations.md).
+This page is about importing code that **actually executes something**. In a `tstl` project, it is common to depend on external library that provide type declarations. Type declaration libraries only provide types: they do not contribute any code to your actual program output. Thus, they work a little differently from what is discussed on this page. For information on how type declarations work, see the [type declarations page](writing-declarations.md).
 :::
 
 ## Adding Lua files to your project sources
 
-The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](type-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
+The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
 
 For example, a project might look like this:
 
@@ -114,7 +114,7 @@ import { someFunction } from "foo";
 someFunction();
 ```
 
-Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](type-declarations.md).
+Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](writing-declarations.md).
 
 ### Creating Lua packages
 
diff --git a/docs/type-declarations.md b/docs/writing-declarations.md
similarity index 98%
rename from docs/type-declarations.md
rename to docs/writing-declarations.md
index 30bd299d..fbe1c643 100644
--- a/docs/type-declarations.md
+++ b/docs/writing-declarations.md
@@ -1,5 +1,5 @@
 ---
-title: Type Declarations
+title: Writing Declarations
 ---
 
 Using TypeScript instead of Lua is useful because everything plugs together in a verifiable way. With that in mind, `tstl` is not very useful unless you pair it with type declarations for your particular Lua environment. That way, TypeScript can catch the typos when you call some API function or use some API variable.
@@ -221,7 +221,7 @@ We recommend reading about Mapped and Conditional types. These things can be use
 
 ## Declaration Merging
 
-https://www.typescriptlang.org/docs/handbook/declaration-merging.html
+Declaration merging is a feature of TypeScript that allows you to combine new declarations with ones that already exist. For more information, see [the TypeScript documentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html).
 
 Some examples of declaration merging have been shown in the above examples.
 
diff --git a/sidebars.json b/sidebars.json
index 9a0fa175..40d8b049 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -3,7 +3,7 @@
         "getting-started",
         "configuration",
         "caveats",
-        "type-declarations",
+        "writing-declarations",
         "the-self-parameter",
         "external-code",
         "publishing-modules",

From 89ca9bf63276da3e5c10abf69f06e5ecd59f531a Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:21:23 -0500
Subject: [PATCH 26/42] fix: package.json fields

---
 docs/publishing-modules.md | 19 +++----------------
 1 file changed, 3 insertions(+), 16 deletions(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index 5022ccdb..cb6522f2 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -34,21 +34,6 @@ Your `package.json` file should include the following fields:
 
 ```json title=package.json
 {
-  "name": "foo",
-  "version": "1.0.0",
-  "description": "A description of your package.",
-  "keywords": ["typescript-to-lua", "lua", "tstl"],
-  "homepage": "https://github.com/AUTHOR_NAME/PROJECT_NAME",
-  "bugs": {
-    "url": "https://github.com/AUTHOR_NAME/PROJECT_NAME/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AUTHOR_NAME/PROJECT_NAME.git"
-  },
-  "license": "MIT",
-  "author": "AUTHOR_NAME",
-  "files": ["dist", "LICENSE", "package.json", "README.md"],
   // Only specify "types" if your library is a type declaration library.
   "types": "./dist/index.d.ts",
   // Only specify "main" if your library is a Lua library.
@@ -57,7 +42,9 @@ Your `package.json` file should include the following fields:
 }
 ```
 
-(Change `AUTHOR_NAME`, `PROJECT_NAME`, and the license accordingly.)
+:::note
+There are many other fields that should be in a proper `package.json` file, such as `name`, `author`, `version`, and so on. Use `npm init` to generate a new `package.json` with some basic fields, if necessary.
+:::
 
 ## Publishing
 

From 37a36113abc45645e01126913cdb5186a4b8e2b1 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:22:35 -0500
Subject: [PATCH 27/42] fix: basic limitations

---
 docs/publishing-modules.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index cb6522f2..9f2d373e 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -12,8 +12,8 @@ This page describes how to create a Lua package and publish it to npm.
 
 ## Basic Limitations
 
-- You cannot import `.ts` and `.tsx` source files.
-- You cannot use `"luaBundle"` in packages intended to be included as dependency in another project.
+- `tstl` cannot import `.ts` and `.tsx` source files from a `node_modules` library.
+- You cannot use the `luaBundle` compiler flag in packages intended to be included as dependency in another project.
 
 ## Project Configuration
 

From c1c74a63195fbd6de1e4343e3b1519ba32b136e0 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:23:56 -0500
Subject: [PATCH 28/42] fix: 5 year old

---
 docs/getting-started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 47843c36..8f385262 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -2,7 +2,7 @@
 title: Getting Started
 ---
 
-Are you ready to start a TypeScript project that will be automatically converted to Lua? This page will help you get started.
+This page will help you set up a new TypeScript project that will be converted to Lua with TypeScriptToLua.
 
 Note that we assume that you are already familiar with how TypeScript works. If you have never coded a project in TypeScript before, or you need a refresher, first read the [official TypeScript tutorial](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html).
 

From 43fa9246a5ec03d544895c0df44ff5d009eb8c33 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:30:43 -0500
Subject: [PATCH 29/42] fix: buzzwords

---
 docs/getting-started.md      | 2 +-
 docs/writing-declarations.md | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 8f385262..99054f60 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -117,7 +117,7 @@ npm run dev
 
 ## Type Declarations
 
-Using TypeScript instead of Lua is useful because everything plugs together in a verifiable way. With that in mind, `tstl` is not very useful unless you pair it with type declarations for your particular Lua environment. That way, TypeScript can catch the typos when you call some API function or use some API variable.
+The best way to use TypeScript is to provide it with information about the format/types of the external functions and variables that you will be using (specific to your environment). This allows the compiler to check your code for mistakes when compiling, instead of having to run the code to find issues. To give TypeScript this information, you will need to provide it with type declarations. You can write these declarations yourself or, if available, install an existing type declarations package for your environment from npm.
 
 For instructions on how to install type declaration packages, see the readme file for the individual package in question. In short, you need to install the package from npm, and then add the following to your `tsconfig.json` file:
 
diff --git a/docs/writing-declarations.md b/docs/writing-declarations.md
index fbe1c643..09b89d56 100644
--- a/docs/writing-declarations.md
+++ b/docs/writing-declarations.md
@@ -2,9 +2,11 @@
 title: Writing Declarations
 ---
 
-Using TypeScript instead of Lua is useful because everything plugs together in a verifiable way. With that in mind, `tstl` is not very useful unless you pair it with type declarations for your particular Lua environment. That way, TypeScript can catch the typos when you call some API function or use some API variable.
+The best way to use TypeScript is to provide it with information about the format/types of the external functions and variables that you will be using (specific to your environment). This allows the compiler to check your code for mistakes when compiling, instead of having to run the code to find issues. To give TypeScript this information, you will need to provide it with type declarations. You can write these declarations yourself or, if available, install an existing type declarations package for your environment from npm.
 
-If you need help writing declarations, feel free to [join our Discord server](https://discord.gg/BWAq58Y).
+For more information about installing existing type definition packages, see the [getting started page](getting-started.md#type-declarations).
+
+This page has more information about how to write your own type declarations. This can be tricky, so if you need help, feel free to [join our Discord server](https://discord.gg/BWAq58Y).
 
 ## About Declaration Files
 

From 33c7bb89e79ac8bcdb9a12e81eea537bb0f6ab0a Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:33:25 -0500
Subject: [PATCH 30/42] fix: remove mixed edge case

---
 docs/publishing-modules.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index 9f2d373e..f4c77b09 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -2,11 +2,10 @@
 title: Publishing Modules
 ---
 
-There are three kinds of `tstl` libraries published on npm:
+There are two kinds of `tstl` libraries published on npm:
 
 - **Type declaration libraries** - Provides only _ambient_ types. In other words, these libraries do not contain any code which can be executed.
 - **Lua libraries** - Provides Lua code that can be imported and executed by `tstl` projects.
-- **Mixed** - Provides **both** type declarations and Lua code at the same time. (These kinds of libraries are less common.)
 
 This page describes how to create a Lua package and publish it to npm.
 

From 5b69da2365e6e605e6436fe65b72f2ae5f510f34 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:37:44 -0500
Subject: [PATCH 31/42] fix: package.json files field

---
 docs/publishing-modules.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index f4c77b09..2fbeab9d 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -33,8 +33,14 @@ Your `package.json` file should include the following fields:
 
 ```json title=package.json
 {
-  // Only specify "types" if your library is a type declaration library.
+  // An array containing the files that will be published to npm. (See more information below.)
+  "files": [
+    "dist/**/*.lua", // Only specify this if your library is a Lua library.
+    "dist/**/*.d.ts"
+  ],
+
   "types": "./dist/index.d.ts",
+
   // Only specify "main" if your library is a Lua library.
   // (Do NOT include the file extension here, or things will not work properly.)
   "main": "./dist/index"
@@ -47,8 +53,6 @@ There are many other fields that should be in a proper `package.json` file, such
 
 ## Publishing
 
-The `files` field in the `package.json` file dictates which specific files will be uploaded to npm.
-
 Note that:
 
 - Regardless of the contents of the `files` field, some files will always be published, like `package.json` and `README.md`.

From cdfa321374b28b584f96abb163014dce043a0e6f Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:40:08 -0500
Subject: [PATCH 32/42] fix: basic limitations

---
 docs/publishing-modules.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/publishing-modules.md b/docs/publishing-modules.md
index 2fbeab9d..3d4e8e53 100644
--- a/docs/publishing-modules.md
+++ b/docs/publishing-modules.md
@@ -12,7 +12,7 @@ This page describes how to create a Lua package and publish it to npm.
 ## Basic Limitations
 
 - `tstl` cannot import `.ts` and `.tsx` source files from a `node_modules` library.
-- You cannot use the `luaBundle` compiler flag in packages intended to be included as dependency in another project.
+- `tstl` Lua libraries can not be bundled with the `luaBundle` compiler flag. (The end-users consuming the library will decide whether they want the final product to use `luaBundle` or not.)
 
 ## Project Configuration
 

From 3875aa8ddf36236d88128978c05a4d8418a240d8 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:41:18 -0500
Subject: [PATCH 33/42] fix: tsconfig

---
 docs/getting-started.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 99054f60..2e4cf26e 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -119,15 +119,7 @@ npm run dev
 
 The best way to use TypeScript is to provide it with information about the format/types of the external functions and variables that you will be using (specific to your environment). This allows the compiler to check your code for mistakes when compiling, instead of having to run the code to find issues. To give TypeScript this information, you will need to provide it with type declarations. You can write these declarations yourself or, if available, install an existing type declarations package for your environment from npm.
 
-For instructions on how to install type declaration packages, see the readme file for the individual package in question. In short, you need to install the package from npm, and then add the following to your `tsconfig.json` file:
-
-```json title=tsconfig.json
-{
-  "compilerOptions": {
-    "types": ["foo"]
-  }
-}
-```
+For instructions on how to install type declaration packages, see the readme file for the individual package in question. In short, you need to install the package from npm, and then add the `types` field to the `compilerOptions` in the `tsconfig.json` file.
 
 ### Type Declaration Packages - Official
 

From 02b4435b1c28dd9d5293adf86d0f11829eb8cd40 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 24 Feb 2023 15:54:45 -0500
Subject: [PATCH 34/42] feat: add computerCraft

---
 docs/getting-started.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2e4cf26e..ed6df8a2 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -137,6 +137,7 @@ Type declarations exist for some common Lua environments:
 Additionally, type declarations exist for some games:
 
 - [The Binding of Isaac: Rebirth](https://isaacscript.github.io)
+- [ComputerCraft (Minecraft)](https://github.com/MCJack123/cc-tstl-template)
 - [Dota 2](https://github.com/ModDota/API/tree/master/declarations/server) ([template](https://github.com/ModDota/TypeScriptAddonTemplate))
 - [Factorio](https://github.com/GlassBricks/typed-factorio)
 - [Garry's Mod](https://github.com/lolleko/gmod-typescript)

From 2f5f2366fbffbab62e6ed481cb0d730f353ce253 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sun, 26 Feb 2023 12:23:16 -0500
Subject: [PATCH 35/42] feat: move file

---
 docs/{ => advanced}/writing-declarations.md | 0
 docs/external-code.md                       | 6 +++---
 sidebars.json                               | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)
 rename docs/{ => advanced}/writing-declarations.md (100%)

diff --git a/docs/writing-declarations.md b/docs/advanced/writing-declarations.md
similarity index 100%
rename from docs/writing-declarations.md
rename to docs/advanced/writing-declarations.md
diff --git a/docs/external-code.md b/docs/external-code.md
index 17fb03c5..c2080535 100644
--- a/docs/external-code.md
+++ b/docs/external-code.md
@@ -5,12 +5,12 @@ title: External Code
 In your `tstl` project, you might want to import some existing Lua code. Or, you might want to import a library from [npm](https://www.npmjs.com/). This page describes how to use external code.
 
 :::note
-This page is about importing code that **actually executes something**. In a `tstl` project, it is common to depend on external library that provide type declarations. Type declaration libraries only provide types: they do not contribute any code to your actual program output. Thus, they work a little differently from what is discussed on this page. For information on how type declarations work, see the [type declarations page](writing-declarations.md).
+This page is about importing code that **actually executes something**. In a `tstl` project, it is common to depend on external library that provide type declarations. Type declaration libraries only provide types: they do not contribute any code to your actual program output. Thus, they work a little differently from what is discussed on this page. For information on how type declarations work, see the [type declarations page](advanced/writing-declarations.md).
 :::
 
 ## Adding Lua files to your project sources
 
-The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
+The most straightforward way to add Lua code is to put the Lua file directly next to your TypeScript files. Next, you add [a declaration file](advanced/writing-declarations.md) with the same name. Then, you can import the Lua code in your TypeScript.
 
 For example, a project might look like this:
 
@@ -114,7 +114,7 @@ import { someFunction } from "foo";
 someFunction();
 ```
 
-Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](writing-declarations.md).
+Since the npm package was presumably made for `tstl` users, it will almost certainly include `.d.ts` files alongside the `.lua` files, which is necessary for `tstl` to import the Lua files properly. If there are no `.d.ts` files, you can try [creating some for the package yourself](advanced/writing-declarations.md).
 
 ### Creating Lua packages
 
diff --git a/sidebars.json b/sidebars.json
index 40d8b049..d6f0b6bc 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -3,11 +3,11 @@
         "getting-started",
         "configuration",
         "caveats",
-        "writing-declarations",
         "the-self-parameter",
         "external-code",
         "publishing-modules",
         "editor-support",
+        "advanced/writing-declarations",
         "advanced/compiler-annotations",
         "advanced/language-extensions",
         "json-modules",

From 7358179bc34e565ea81035b3be0a13ecb728d8f8 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sun, 26 Feb 2023 12:28:48 -0500
Subject: [PATCH 36/42] feat: adding sidebar categories + adding missing
 package.json script

---
 docs/{ => advanced}/json-modules.md |  0
 docs/{ => advanced}/jsx.md          |  0
 package.json                        |  1 +
 sidebars.json                       | 36 +++++++++++++++++++----------
 4 files changed, 25 insertions(+), 12 deletions(-)
 rename docs/{ => advanced}/json-modules.md (100%)
 rename docs/{ => advanced}/jsx.md (100%)

diff --git a/docs/json-modules.md b/docs/advanced/json-modules.md
similarity index 100%
rename from docs/json-modules.md
rename to docs/advanced/json-modules.md
diff --git a/docs/jsx.md b/docs/advanced/jsx.md
similarity index 100%
rename from docs/jsx.md
rename to docs/advanced/jsx.md
diff --git a/package.json b/package.json
index bb8127ea..22060829 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,7 @@
     "scripts": {
         "start": "docusaurus start",
         "build": "docusaurus build",
+        "serve": "docusaurus serve",
         "lint": "npm run lint:prettier",
         "lint:prettier": "prettier --check .",
         "fix:prettier": "prettier --write .",
diff --git a/sidebars.json b/sidebars.json
index d6f0b6bc..0e77432d 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -1,17 +1,29 @@
 {
     "docs": [
-        "getting-started",
-        "configuration",
-        "caveats",
-        "the-self-parameter",
-        "external-code",
-        "publishing-modules",
-        "editor-support",
-        "advanced/writing-declarations",
-        "advanced/compiler-annotations",
-        "advanced/language-extensions",
-        "json-modules",
-        "jsx",
+        {
+            "type": "category",
+            "label": "Basic",
+            "items": [
+                "getting-started",
+                "configuration",
+                "caveats",
+                "the-self-parameter",
+                "external-code",
+                "publishing-modules",
+                "editor-support"
+            ]
+        },
+        {
+            "type": "category",
+            "label": "Advanced",
+            "items": [
+                "advanced/writing-declarations",
+                "advanced/compiler-annotations",
+                "advanced/language-extensions",
+                "advanced/json-modules",
+                "advanced/jsx"
+            ]
+        },
         {
             "type": "category",
             "label": "API",

From cc2e3b4d825f23e218bd600db47c3304e8fe752b Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 28 Feb 2023 12:52:34 -0500
Subject: [PATCH 37/42] feat: section on null

---
 docs/caveats.md | 66 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 48 insertions(+), 18 deletions(-)

diff --git a/docs/caveats.md b/docs/caveats.md
index ec8f4f26..ba528827 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -2,6 +2,10 @@
 title: Caveats
 ---
 
+Luckily, for most use-cases, you can write modern, idiomatic TypeScript, and TSTL will produce transpiled Lua that will work flawlessly. In other words, you probably will not have to worry about the idiomatic quirks of Lua or the internal decisions that TSTL makes when converting code.
+
+With that said, TSTL does have some "gotchas" that you might run into. This page covers some of those edge-cases.
+
 ## Feature support
 
 | Feature             | Lua 5.0 | Lua 5.1 | Lua 5.2 | Lua 5.3 | LuaJIT |
@@ -17,7 +21,7 @@ title: Caveats
 
 ## Differences from JavaScript
 
-This project aims for both compilation results to have the same behavior as much as possible, but not at all costs. Since TypeScript is based on JavaScript it also inherited some of the quirks in JavaScript that are not present in Lua. This is where behavior between Lua and JavaScript compilation targets diverge. TypeScriptToLua aims to keep identical behavior as long as **sane** TypeScript is used: if JavaScript-specific quirks are used behavior might differ.
+This project aims for both compilation results to have the same behavior as much as possible, but not at all costs. Since TypeScript is based on JavaScript, it also inherited some of the quirks in JavaScript that are not present in Lua. This is where behavior between Lua and JavaScript compilation targets diverge. TypeScriptToLua aims to keep identical behavior as long as **sane** TypeScript is used: if JavaScript-specific quirks are used, behavior might differ.
 
 Below are some of the cases where resulting Lua intentionally behaves different from compiled JS.
 
@@ -39,49 +43,75 @@ JavaScript and Lua differ in what they evaluate to true/false. TypeScriptToLua a
 | `0`               | `false`               | ⚠️`true`       |
 | (Everything else) | `true`                | `true`         |
 
+We recommend that you use the [`strict-boolean-expression`](https://typescript-eslint.io/rules/strict-boolean-expressions/) ESLint rule in your TSTL projects, which will force you to be explicit and prevent this class of bug entirely.
+
+(In general, it is a good idea to have a fleshed out linting setup for all TypeScript projects, regardless of whether it is a normal TypeScript project or a TSTL project. If you are new to TypeScript and want a quick linting setup, or you want to adopt a mature, fleshed out linting config, then you can try the [`isaacscript-lint`](https://github.com/IsaacScript/isaacscript/tree/main/packages/isaacscript-lint) meta-package.)
+
 ### [Loose equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Loose_equality_using)
 
 TypeScriptToLua makes no difference between `==` and `===` when compiling to Lua, treating all comparisons as strict (`===`).
 
+We recommend that you use the [`eqeqeq`](https://eslint.org/docs/latest/rules/eqeqeq) ESLint rule, which will force you to be explicit and prevent this class of bug entirely.
+
+### `undefined` and `null`
+
+In JavaScript, there are two kinds of "zero-value" states: `undefined` and `null`. These two states have different kinds of properties. Specifically, `null` is a value that "really exists". For example:
+
+```ts
+const foo = {
+  someProp1: 123,
+  someProp2: null,
+  someProp3: undefined,
+}
+```
+
+When iterating over the keys of `foo`, we would obviously get `someProp1`. We would also get `someProp2`, because null is a "real" value. However, we would not get `someProp3`, because setting an object value to undefined is the same operation is deleting the key (and/or the key/value pair not existing at all).
+
+`nil` is the Lua equivalent for `undefined`, so TSTL converts `undefined` to `nil`. However, there is no Lua equivlanet for `null`, so TSTL converts `null` to `nil` as well.
+
+This means that TSTL programs with `null` will have different behavior than JavaScript/TypeScript programs. In the above example, if we iterated over `foo` in a TSTL program, we would _only_ get `someProp1` (instead of both `someProp1` and `someProp2`).
+
+In general, we recommend keeping `null` out of your TSTL codebases in favor of `undefined`. Not only will this represent the transpiled Lua code better, [it is more idiomatic in TypeScript to prefer `undefined` over `null` when both would accomplish the same thing](https://basarat.gitbook.io/typescript/recap/null-undefined).
+
 ### Array Length
 
-`Array.prototype.length` is translated to Lua's `#` operator. Due to the way lists are implemented in Lua there can be differences between JavaScript's `list.length` and Lua's `#list`. The transpiler does not do anything to remedy these differences, so when working with lists, the transpiled Lua will use the standard Lua conventions. Generally speaking, the situation where these differences occur happen when adding/removing items to a list in a hacky way, or when setting list items to `undefined`/`null`.
+`Array.prototype.length` is translated to Lua's `#` operator. Due to the way arrays are implemented in Lua, there can be differences between JavaScript's `myArray.length` and Lua's `#myArray`. The transpiler does not do anything to remedy these differences. Thus, when working with arrays, the transpiled Lua will use the standard Lua conventions. Generally speaking, the situation where these differences occur happen when adding/removing items to an array in a hacky way, or when setting array items to `undefined` / `null`.
 
-**Examples:**
+For example:
 
-**Safe (no difference):**
+#### Safe (no difference)
 
 ```ts
-const myList = [1, 2, 3];
-myList.push(4);
-myList.pop();
-myList.splice(1, 1);
-// myList.length == 2
+const myArray = [1, 2, 3];
+myArray.push(4);
+myArray.pop();
+myArray.splice(1, 1);
+// myArray.length == 2
 ```
 
-**Differences might occur:**
+#### Differences might occur
 
 ```ts
-const myList = [1, 2, 3];
-myList[1] = undefined;
-// myList.length == 1 (3 in JavaScript)
+const myArray = [1, 2, 3];
+myArray[1] = undefined;
+// myArray.length == 1 (which would be 3 in JavaScript)
 ```
 
 ```ts
-const myList = [1, 2, 3];
-myList[4] = 5;
-// myList.length == 3 (5 in JavaScript)
+const myArray = [1, 2, 3];
+myArray[4] = 5;
+// myArray.length == 3 (which would be 5 in JavaScript)
 ```
 
 ### Key Iteration Order
 
 Even though iterating over object keys with `for ... in` does not guarantee order in either JavaScript or Lua. Therefore, the iteration order in JavaScript is likely different from the order in Lua.
 
-**Note:** If a specific order is required, it is better to use ordered collections like lists instead.
+**Note:** If a specific order is required, it is better to use ordered collections like arrays instead.
 
 ### Iterating an array with `for ... in`
 
-Not allowed.
+Not allowed. Use a `for of` loop instead to iterate over an array.
 
 ### Sorting
 

From 329fe6207276e17893412c7ea880773164a51a7d Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 28 Feb 2023 15:02:46 -0500
Subject: [PATCH 38/42] Update docs/advanced/writing-declarations.md

Co-authored-by: Perry van Wesel <Perryvw@users.noreply.github.com>
---
 docs/advanced/writing-declarations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/advanced/writing-declarations.md b/docs/advanced/writing-declarations.md
index 09b89d56..6d6d90ba 100644
--- a/docs/advanced/writing-declarations.md
+++ b/docs/advanced/writing-declarations.md
@@ -10,7 +10,7 @@ This page has more information about how to write your own type declarations. Th
 
 ## About Declaration Files
 
-Declaration files end with the extension `.d.ts` (which stands for "declaration TypeScript file"). Declaration files are different from normal `.ts` files in that they must only contain _ambient_ code. In the context of TypeScript, _ambient_ refers to code that not emitted into the actual program output.
+Declaration files end with the extension `.d.ts` (which stands for "declaration TypeScript file"). Declaration files are different from normal `.ts` files in that they must only contain _ambient_ code. In the context of TypeScript, _ambient_ refers to code that only exists at compile-time and is not emitted into the program output.
 
 In other words, anything you put into a `.d.ts` file will inform the TypeScript compiler about what the format of something is. And it will never appear in the generated `.lua` file(s).
 

From 14e7b6d534ed31225c304ccba48c87912a5613a4 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 28 Feb 2023 15:06:04 -0500
Subject: [PATCH 39/42] fix: remove isaacscript-lint

---
 docs/caveats.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/caveats.md b/docs/caveats.md
index ba528827..61092b11 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -45,8 +45,6 @@ JavaScript and Lua differ in what they evaluate to true/false. TypeScriptToLua a
 
 We recommend that you use the [`strict-boolean-expression`](https://typescript-eslint.io/rules/strict-boolean-expressions/) ESLint rule in your TSTL projects, which will force you to be explicit and prevent this class of bug entirely.
 
-(In general, it is a good idea to have a fleshed out linting setup for all TypeScript projects, regardless of whether it is a normal TypeScript project or a TSTL project. If you are new to TypeScript and want a quick linting setup, or you want to adopt a mature, fleshed out linting config, then you can try the [`isaacscript-lint`](https://github.com/IsaacScript/isaacscript/tree/main/packages/isaacscript-lint) meta-package.)
-
 ### [Loose equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Loose_equality_using)
 
 TypeScriptToLua makes no difference between `==` and `===` when compiling to Lua, treating all comparisons as strict (`===`).

From 906cf772eed2f02e9422618d0e7d9a8845811752 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 28 Feb 2023 15:08:18 -0500
Subject: [PATCH 40/42] fix: rename files

---
 docs/{advanced => }/json-modules.md | 0
 docs/{advanced => }/jsx.md          | 0
 sidebars.json                       | 4 ++--
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename docs/{advanced => }/json-modules.md (100%)
 rename docs/{advanced => }/jsx.md (100%)

diff --git a/docs/advanced/json-modules.md b/docs/json-modules.md
similarity index 100%
rename from docs/advanced/json-modules.md
rename to docs/json-modules.md
diff --git a/docs/advanced/jsx.md b/docs/jsx.md
similarity index 100%
rename from docs/advanced/jsx.md
rename to docs/jsx.md
diff --git a/sidebars.json b/sidebars.json
index 0e77432d..34a32cbc 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -20,8 +20,8 @@
                 "advanced/writing-declarations",
                 "advanced/compiler-annotations",
                 "advanced/language-extensions",
-                "advanced/json-modules",
-                "advanced/jsx"
+                "json-modules",
+                "jsx"
             ]
         },
         {

From 9f7c4d24ff7e1ac65dc7f089c7021eb1fc607b46 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 28 Feb 2023 15:11:53 -0500
Subject: [PATCH 41/42] fix: less text in undefined section

---
 docs/caveats.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/caveats.md b/docs/caveats.md
index 61092b11..c8475e35 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -53,7 +53,9 @@ We recommend that you use the [`eqeqeq`](https://eslint.org/docs/latest/rules/eq
 
 ### `undefined` and `null`
 
-In JavaScript, there are two kinds of "zero-value" states: `undefined` and `null`. These two states have different kinds of properties. Specifically, `null` is a value that "really exists". For example:
+`nil` is the Lua equivalent for `undefined`, so TSTL converts `undefined` to `nil`. However, there is no Lua equivlanet for `null`, so TSTL converts `null` to `nil` as well.
+
+This means that TSTL programs with `null` will have different behavior than JavaScript/TypeScript programs. For example:
 
 ```ts
 const foo = {
@@ -63,13 +65,9 @@ const foo = {
 }
 ```
 
-When iterating over the keys of `foo`, we would obviously get `someProp1`. We would also get `someProp2`, because null is a "real" value. However, we would not get `someProp3`, because setting an object value to undefined is the same operation is deleting the key (and/or the key/value pair not existing at all).
-
-`nil` is the Lua equivalent for `undefined`, so TSTL converts `undefined` to `nil`. However, there is no Lua equivlanet for `null`, so TSTL converts `null` to `nil` as well.
-
-This means that TSTL programs with `null` will have different behavior than JavaScript/TypeScript programs. In the above example, if we iterated over `foo` in a TSTL program, we would _only_ get `someProp1` (instead of both `someProp1` and `someProp2`).
+If we iterated over `foo` in a TSTL program, we would _only_ get `someProp1`, instead of both `someProp1` and `someProp2` like we would in a JavaScript/TypeScript program.
 
-In general, we recommend keeping `null` out of your TSTL codebases in favor of `undefined`. Not only will this represent the transpiled Lua code better, [it is more idiomatic in TypeScript to prefer `undefined` over `null` when both would accomplish the same thing](https://basarat.gitbook.io/typescript/recap/null-undefined).
+In general, we recommend keeping `null` out of your TSTL codebases in favor of `undefined`. Not only will this represent the transpiled Lua code better, but [it is more idiomatic in TypeScript to prefer `undefined` over `null` when both would accomplish the same thing](https://basarat.gitbook.io/typescript/recap/null-undefined).
 
 ### Array Length
 

From 7c4ee3fa9a0a3efda06f50cdee09d52de1bc039a Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 28 Feb 2023 15:12:51 -0500
Subject: [PATCH 42/42] fix: prettier

---
 docs/caveats.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/caveats.md b/docs/caveats.md
index c8475e35..dcdf1017 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -62,7 +62,7 @@ const foo = {
   someProp1: 123,
   someProp2: null,
   someProp3: undefined,
-}
+};
 ```
 
 If we iterated over `foo` in a TSTL program, we would _only_ get `someProp1`, instead of both `someProp1` and `someProp2` like we would in a JavaScript/TypeScript program.