Move over some of the new handbook TSConfig docs

README.md

@@ -16,6 +16,10 @@ code .
 
 The main website for TypeScript, a Gatsby website which is statically deployed.
 
+```sh
+yarn start
+```
+
 ## Playground
 
 A React component for the TypeScript playground base component. Not the one available on

packages/tsconfig-reference/README.md

@@ -27,5 +27,12 @@ If you'd like to create a new language:
 The TSConfig reference is created by a two step process:
 
 - Creating the JSON dump of all the useful info via [`./scripts/generateJSON.ts`](scripts/generateJSON.ts) which you can find in [`./data`](./data).
+- A script which uses the JSON, and the copy to generate per-language markdown docs which are picked up by the typescriptlang-org Gatsby site at `http://localhost:8000/tsconfig`
 
-- A script which uses the JSON, and the copy to generate per-language markdown docs which are meant to be embedded inside webpages ``
+You can run these commands from the root of the repo:
+
+```sh
+yarn workspace tsconfig-reference run generate-json
+
+yarn workspace tsconfig-reference run generate-markdown
+```

packages/tsconfig-reference/copy/en/categories/Project_Files_0.md

@@ -0,0 +1,5 @@
+---
+display: "Project File Inclusion"
+---
+
+

packages/tsconfig-reference/copy/en/options/allowUnreachableCode.md

@@ -2,4 +2,19 @@
 display: "Allow Unreachable Code"
 ---
 
-Do not report errors on unreachable code.
+Disables warnings about unreachable code.
+These warnings are only about code which is provably unreachable due to syntactic construction, like the example below.
+
+```ts
+// @allowUnreachableCode: false
+function fn(n: number) {
+   if (n > 5) {
+      return true;
+   } else {
+      return false;
+   }
+   return true;
+}
+```
+
+TypeScript doesn't error on the basis of code which *appears* to be unreachable due to type analysis.

packages/tsconfig-reference/copy/en/options/allowUnusedLabels.md

@@ -2,4 +2,16 @@
 display: "Allow Unused Labels"
 ---
 
-Do not report errors on unused labels.
+Disables warnings about unused labels.
+Labels are very rare in JavaScript and typically indicate an attempt to write an object literal:
+
+```ts
+// @allowUnusedLabels: false
+function f(a: number) {
+   // Forgot 'return' statement!
+   if (a > 10)
+   {
+       m: 0
+   }
+}
+```

packages/tsconfig-reference/copy/en/options/charset.md

@@ -2,4 +2,7 @@
 display: "Charset"
 ---
 
-The character set of the input files.
+> ❌ **Deprecated:** This option does nothing.
+
+In prior versions of TypeScript, this controlled what encoding was used when reading text files from disk.
+Today, TypeScript assumes UTF-8 encoding, but will correctly detect UTF-16 (BE and LE) or UTF-8 BOMs.

packages/tsconfig-reference/copy/en/options/composite.md

@@ -2,4 +2,10 @@
 display: "Composite"
 ---
 
-Enable project compilation
+The `composite` option enforces certain constraints that make it possible for build tools (including TypeScript itself, under `--build` mode) to quickly determine if a project has been built yet.
+
+When this setting is on:
+
+ * The `rootDir` setting, if not explicitly set, defaults to the directory containing the `tsconfig.json` file.
+ * All implementation files must be matched by an `include` pattern or listed in the `files` array. If this constraint is violated, `tsc` will inform you which files weren't specified.
+ * `declaration` defaults to `true`

packages/tsconfig-reference/copy/en/options/declarationMap.md

@@ -2,4 +2,8 @@
 display: "Declaration Map"
 ---
 
-Generates a sourcemap for each corresponding '.d.ts' file.
+
+Generates a source map for `.d.ts` files that maps back to the original `.ts` source file.
+This will allow editors such as VS Code to go to the original `.ts` file when using features like *Go to Definition*.
+
+You should strongly consider turning this on if you're using project references.

packages/tsconfig-reference/copy/en/options/downlevelIteration.md

@@ -2,4 +2,72 @@
 display: "Downlevel Iteration"
 ---
 
-Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'.
+**Default**: `false`. Has no effect if `target` is ES6 or newer.
+
+ECMAScript 6 added several new iteration primitives: the `for / of` loop (`for (el of arr)`), Array spread (`[a, ...b]`), argument spread (`fn(...args)`), and `Symbol.iterator`.
+`--downlevelIteration` allows for these iteration primitives to be used more accurately in ES5 environments if a `Symbol.iterator` implementation is present.
+
+#### Example: Effects on `for / of`
+
+Without `downlevelIteration` on, a `for / of` loop on any object is downleveled to a traditional `for` loop:
+
+```ts
+// @target: ES5
+// @showEmit
+const str = "Hello!";
+for (const s of str) {
+    console.log(s);
+}
+```
+
+This is often what people expect, but it's not 100% compliant with ECMAScript 6 behavior.
+Certain strings, such as emoji (😜), have a `.length` of 2 (or even more!), but should iterate as 1 unit in a `for-of` loop.
+See [this blog post by Jonathan New](https://blog.jonnew.com/posts/poo-dot-length-equals-two) for a longer explanation.
+
+When `downlevelIteration` is enabled, TypeScript will use a helper function that checks for a `Symbol.iterator` implementation (either native or polyfill).
+If this implementation is missing, you'll fall back to index-based iteration.
+
+```ts
+// @target: ES5
+// @downlevelIteration
+// @showEmit
+const str = "Hello!";
+for (const s of str) {
+    console.log(s);
+}
+```
+
+>> **Note:** Remember, `downlevelIteration` does not improve compliance if `Symbol.iterator` is not present!
+
+#### Example: Effects on Array Spreads
+
+This is an array spread:
+
+```js
+// Make a new array who elements are 1 followed by the elements of arr2
+const arr = [1, ...arr2];
+```
+
+Based on the description, it sounds easy to downlevel to ES5:
+
+```js
+// The same, right?
+const arr = [1].concat(arr2);
+```
+
+However, this is observably different in certain rare cases.
+For example, if an array has a "hole" in it, the missing index will create an *own* property if spreaded, but will not if built using `concat`:
+
+```js
+// Make an array where the '1' element is missing
+let missing = [0, , 1];
+let spreaded = [...missing];
+let concated = [].concat(missing);
+
+// true
+"1" in spreaded
+// false
+"1" in concated
+```
+
+Just as with `for / of`, `downlevelIteration` will use `Symbol.iterator` (if present) to more accurately emulate ES 6 behavior.

packages/tsconfig-reference/copy/en/options/emitBOM.md

@@ -2,4 +2,6 @@
 display: "Emit B O M"
 ---
 
-Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.
+Controls whether TypeScript will emit a [byte order mark (BOM)](https://en.wikipedia.org/wiki/Byte_order_mark) when writing output files.
+Some runtime environments require a BOM to correctly interpret a JavaScript files; others require that it is not present.
+The default value of `false` is generally best unless you have a reason to change it.

packages/tsconfig-reference/copy/en/options/emitDeclarationOnly.md

@@ -2,4 +2,6 @@
 display: "Emit Declaration Only"
 ---
 
-Only emit '.d.ts' declaration files.
+*Only* emit `.d.ts` files; do not emit `.js` files.
+
+This setting is useful if you're using a transpiler other than TypeScript to generate your JavaScript.

packages/tsconfig-reference/copy/en/options/exclude.md

@@ -0,0 +1,11 @@
+---
+display: "Exclude"
+---
+
+**Default**: `["node_modules", "bower_components", "jspm_packages"]`, plus the value of `outDir` if one is specified.
+
+Specifies an array of filenames or patterns that should be skipped when resolving `include`.
+
+**Important**: `exclude` *only* changes which files are included as a result of the `include` setting.
+A file specified by `exclude` can still become part of your program due to an `import` statement in your code, a `types` inclusion, a `/// <reference` directive, or being specified in the `files` list.
+It is not a mechanism that **prevents** a file from being included in the program - it simply changes what the `include` setting finds.

packages/tsconfig-reference/copy/en/options/extends.md

@@ -0,0 +1,5 @@
+---
+display: "Extends"
+---
+
+TODO

packages/tsconfig-reference/copy/en/options/files.md

@@ -0,0 +1,6 @@
+---
+display: "Files"
+---
+
+Specifies an array of files to include in the program.
+An error occurs if any of the files can't be found.

packages/tsconfig-reference/copy/en/options/forceConsistentCasingInFileNames.md

@@ -2,4 +2,10 @@
 display: "Force Consistent Casing In File Names"
 ---
 
-Disallow inconsistently-cased references to the same file.
+TypeScript follows the case sensitivity rules of the file system it's running on.
+This can be problematic if some developers are working in a case-sensitive file system and others aren't.
+If a file attempts to import `fileManager.ts` by specifying `./FileManager.ts` the file will be found in a case-insensitive file system, but not on a case-sensitive file system.
+
+When this option is set, TypeScript will issue an error if a program tries to include a file by a casing different from the casing on disk.
+
+We recommend enabling this option in all projects.

packages/tsconfig-reference/copy/en/options/importHelpers.md

@@ -2,4 +2,48 @@
 display: "Import Helpers"
 ---
 
-Import emit helpers from 'tslib'.
+For certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays/objects, and async operations.
+By default, these helpers are inserted into files which use them.
+This can result in code duplication if the same helper is used in many different modules.
+
+If the `importHelpers` flag is on, these helper functions are instead imported from the [tslib](https://www.npmjs.com/package/tslib) module.
+You will need to ensure that the `tslib` module is able to be imported at runtime.
+This only affects modules; global script files will not attempt to import modules.
+
+```ts
+// @showEmit
+// @target: ES5
+// @downleveliteration
+// --importHelpers off: Spread helper is inserted into the file
+// Note: This example also uses --downlevelIteration
+export function fn(arr: number[]) {
+   const arr2 = [1, ...arr];
+}
+```
+
+```ts
+// @showEmit
+// @target: ES5
+// @downleveliteration
+// @importhelpers
+// --importHelpers on: Spread helper is inserted imported from 'tslib'
+export function fn(arr: number[]) {
+   const arr2 = [1, ...arr];
+}
+```
+
+### `noEmitHelpers`
+
+Instead of importing helpers with [[importHelpers]], you can provide implementations in the global scope for the helpers you use and completely turn off emitting of helper functions:
+
+```ts
+// @showEmit
+// @target: ES5
+// @downleveliteration
+// @noemithelpers
+
+// __spread is assumed to be available
+export function fn(arr: number[]) {
+   const arr2 = [1, ...arr];
+}
+```

packages/tsconfig-reference/copy/en/options/include.md

@@ -0,0 +1,22 @@
+---
+display: "Include"
+---
+
+**Default**: `[]` if `files` is specified, otherwise `["**/*"]`
+
+
+```json
+{
+   "include": ["src/**", "tests/**"]
+}
+```
+
+Specifies an array of filenames or patterns to include in the program.
+These filenames are resolved relative to the directory containing the `tsconfig.json` file.
+
+`include` and `exclude` support wildcard characters to make glob patterns:
+ * `*` matches zero or more characters (excluding directory separators)
+ * `?` matches any one character (excluding directory separators)
+ * `**/` recursively matches any subdirectory
+
+If a glob pattern doesn't include a file extension, then only files with supported extensions are included (e.g. `.ts`, `.tsx`, and `.d.ts` by default, with `.js` and `.jsx` if `allowJs` is set to true).

packages/tsconfig-reference/copy/en/options/inlineSourceMap.md

@@ -2,4 +2,8 @@
 display: "Inline Source Map"
 ---
 
-Emit a single file with source maps instead of having a separate file.
+When set, instead of writing out a `.js.map` file to provide source maps, TypeScript will embed the source map content in the `.js` files.
+Although this results in larger JS files, it can be convenient in some scenarios.
+For example, you might want to debug JS files on a webserver that doesn't allow `.map` files to be served.
+
+Mutually exclusive with `sourceMap`.

packages/tsconfig-reference/copy/en/options/inlineSources.md

@@ -2,4 +2,7 @@
 display: "Inline Sources"
 ---
 
-Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set.
+When set, TypeScript will include the original content of the `.ts` file as an embedded string in the source map.
+This is often useful in the same cases as `inlineSourceMap`.
+
+Requires either `sourceMap` or `inlineSourceMap` to be set.

packages/tsconfig-reference/copy/en/options/isolatedModules.md

@@ -2,4 +2,60 @@
 display: "Isolated Modules"
 ---
 
-Transpile each file as a separate module (similar to 'ts.transpileModule').
+While you can use TypeScript to produce JavaScript code from TypeScript code, it's also common to use other transpilers such as [Babel](https://babeljs.io) to do this.
+However, most other transpilers only operate on a single file at a time, so can't apply code transforms that depend on whole-program analysis.
+This restriction also applies to TypeScript's `ts.transpileModule` API which is used by some build tools.
+
+These limitations can cause runtime problems for some TypeScript constructs.
+Setting the `isolatedModules` flag tells TypeScript to warn you if you write certain code that can't be correctly interpreted by a single-file transpilation process.
+It does not change the behavior of your code, or otherwise change the behavior of TypeScript's checking and emitting process.
+
+#### Exports of Non-Value Identifiers
+
+In TypeScript, you can import a *type* and then subsequently export it:
+```ts
+// @noErrors
+import { someType, someFunction } from "someModule";
+
+someFunction();
+
+export { someType, someFunction };
+```
+
+Because there's no value for `someType`, the emitted `export` will not try to export it (this would be a runtime error):
+
+```js
+export { someFunction };
+```
+
+Single-file transpilers don't know whether `someType` produces a value or not, so it's an error to export a name that only refers to a type if `isolatedModules` is set.
+
+#### Non-Module Files
+
+If `isolatedModules` is set, all implementation files must be *modules*.
+An error occurs if any file isn't a module:
+
+```ts
+// @isolatedModules
+function fn() { }
+```
+
+This restriction doesn't apply to `.d.ts` files
+
+#### References to `const enum` members
+
+In TypeScript, when you reference a `const enum` member, the reference is replaced by its actual value in the emitted JavaScript:
+
+```ts
+// @showEmit
+// @removeComments
+declare const enum Numbers {
+   Zero = 0,
+   One = 1
+}
+console.log(Numbers.Zero + Numbers.One);
+```
+
+Without knowledge of the values of these members, other transpilers can't replace the references to `Number`, which would be a runtime error if left alone (since there is no `Numbers` object at runtime).
+Because of this, when `isolatedModules` is set, it is an error to reference an ambient `const enum` member.
+

packages/tsconfig-reference/copy/en/options/jsx.md

@@ -1,5 +1,12 @@
 ---
-display: "JSx"
+display: "JSX"
 ---
 
-Specify JSX code generation: 'preserve', 'react-native', or 'react'.
+**Allowed Values**: `react` (default), `react-native`, `preserve`
+
+Controls how JSX constructs are emitted in JavaScript files.
+This only affects output of JS files that started in `.tsx` files.
+
+ * `preserve`: Emit `.jsx` files with the JSX unchanged
+ * `react`: Emit `.js` files with JSX changed to the equivalent `React.createElement` calls
+ * `react-native`: Emit `.js` files with the JSX unchanged