diff --git a/.prettierignore b/.prettierignore
index b830eb822..3afc6e862 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -8,6 +8,7 @@
 !/tests
 !/website
 /website/.docusaurus
+/website/build
 /website/docs
 /website/readme-sources
 /website/static
diff --git a/src/index.ts b/src/index.ts
index 996556a7a..70dfe109b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -183,6 +183,8 @@ export const VERSION = require('../package.json').version;
 
 /**
  * Options for creating a new TypeScript compiler instance.
+
+ * @category Basic
  */
 export interface CreateOptions {
   /**
@@ -367,7 +369,9 @@ export interface CreateOptions {
    */
   tsTrace?: (str: string) => void;
   /**
-   * TODO DOCS YAY
+   * Enable native ESM support.
+   *
+   * For details, see https://typestrong.org/ts-node/docs/imports#native-ecmascript-modules
    */
   esm?: boolean;
   /**
@@ -392,6 +396,8 @@ export interface OptionBasePaths {
 
 /**
  * Options for registering a TypeScript compiler instance globally.
+
+ * @category Basic
  */
 export interface RegisterOptions extends CreateOptions {
   /**
@@ -548,10 +554,14 @@ export function getExtensions(config: _ts.ParsedCommandLine) {
 
 /**
  * Create a new TypeScript compiler instance and register it onto node.js
+
+ * @category Basic
  */
 export function register(opts?: RegisterOptions): Service;
 /**
  * Register TypeScript compiler instance onto node.js
+
+ * @category Basic
  */
 export function register(service: Service): Service;
 export function register(
@@ -591,6 +601,8 @@ export function register(
 
 /**
  * Create TypeScript compiler instance.
+ *
+ * @category Basic
  */
 export function create(rawOptions: CreateOptions = {}): Service {
   const foundConfigResult = findAndReadConfig(rawOptions);
@@ -1585,6 +1597,8 @@ function getTokenAtPosition(
  *
  * Node changed the hooks API, so there are two possible APIs.  This function
  * detects your node version and returns the appropriate API.
+ *
+ * @category ESM Loader
  */
 export const createEsmHooks: typeof createEsmHooksFn = (
   tsNodeService: Service
diff --git a/src/repl.ts b/src/repl.ts
index c6371bdbb..21935ddbb 100644
--- a/src/repl.ts
+++ b/src/repl.ts
@@ -115,6 +115,7 @@ export interface ReplService {
   readonly console: Console;
 }
 
+/** @category REPL */
 export interface CreateReplOptions {
   service?: Service;
   state?: EvalState;
@@ -144,6 +145,8 @@ export interface CreateReplOptions {
  *     const service = tsNode.create({...repl.evalAwarePartialHost});
  *     repl.setService(service);
  *     repl.start();
+ *
+ * @category REPL
  */
 export function createRepl(options: CreateReplOptions = {}) {
   const { ignoreDiagnosticsThatAreAnnoyingInInteractiveRepl = true } = options;
diff --git a/src/transpilers/types.ts b/src/transpilers/types.ts
index 641deb4c1..a15b10a4c 100644
--- a/src/transpilers/types.ts
+++ b/src/transpilers/types.ts
@@ -5,16 +5,21 @@ import type { ProjectLocalResolveHelper } from '../util';
 /**
  * Third-party transpilers are implemented as a CommonJS module with a
  * named export "create"
+ *
+ * @category Transpiler
  */
 export interface TranspilerModule {
   create: TranspilerFactory;
 }
 /**
  * Called by ts-node to create a custom transpiler.
+ *
+ * @category Transpiler
  */
 export type TranspilerFactory = (
   options: CreateTranspilerOptions
 ) => Transpiler;
+/** @category Transpiler */
 export interface CreateTranspilerOptions {
   // TODO this is confusing because its only a partial Service.  Rename?
   // Careful: must avoid stripInternal breakage by guarding with Extract<>
@@ -30,15 +35,18 @@ export interface CreateTranspilerOptions {
    */
   transpilerConfigLocalResolveHelper: ProjectLocalResolveHelper;
 }
+/** @category Transpiler */
 export interface Transpiler {
   // TODOs
   // Create spec for returning diagnostics?  Currently transpilers are allowed to
   // throw an error but that's it.
   transpile(input: string, options: TranspileOptions): TranspileOutput;
 }
+/** @category Transpiler */
 export interface TranspileOptions {
   fileName: string;
 }
+/** @category Transpiler */
 export interface TranspileOutput {
   outputText: string;
   diagnostics?: ts.Diagnostic[];
diff --git a/tsconfig.json b/tsconfig.json
index 158695d23..2b2231bf2 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -24,6 +24,10 @@
   "typedocOptions": {
     "entryPoints": ["./src/index.ts"],
     "readme": "none",
-    "out": "website/static/api"
+    "out": "website/static/api",
+    "excludeTags": ["allof"],
+    "categorizeByGroup": false,
+    "categoryOrder": ["Basic", "REPL", "Transpiler", "ESM Loader", "Other"],
+    "defaultCategory": "Other"
   }
 }
diff --git a/website/docs/api.md b/website/docs/api.md
new file mode 100644
index 000000000..182e845b3
--- /dev/null
+++ b/website/docs/api.md
@@ -0,0 +1,14 @@
+---
+title: API
+---
+
+ts-node's complete API is documented here: [API Docs](https://typestrong.org/ts-node/api/)
+
+Here are a few highlights of what you can accomplish:
+
+- [`create()`](https://typestrong.org/ts-node/api/index.html#create) creates ts-node's compiler service without
+registering any hooks.
+- [`createRepl()`](https://typestrong.org/ts-node/api/index.html#createRepl) creates an instance of our REPL service, so
+you can create your own TypeScript-powered REPLs.
+- [`createEsmHooks()`](https://typestrong.org/ts-node/api/index.html#createEsmHooks) creates our ESM loader hooks,
+suitable for composing with other loaders or augmenting with additional features.
diff --git a/website/docs/imports.md b/website/docs/commonjs-vs-native-ecmascript-modules.md
similarity index 99%
rename from website/docs/imports.md
rename to website/docs/commonjs-vs-native-ecmascript-modules.md
index 4a0ea5c7b..b433438dd 100644
--- a/website/docs/imports.md
+++ b/website/docs/commonjs-vs-native-ecmascript-modules.md
@@ -1,5 +1,6 @@
 ---
 title: "CommonJS vs native ECMAScript modules"
+slug: imports
 ---
 
 TypeScript is almost always written using modern `import` syntax, but it is also transformed before being executed by the underlying runtime.  You can choose to either transform to CommonJS or to preserve the native `import` syntax, using node's native ESM support.  Configuration is different for each.
diff --git a/website/docs/how-it-works.md b/website/docs/how-it-works.md
index f75f32c3f..d9f2f700c 100644
--- a/website/docs/how-it-works.md
+++ b/website/docs/how-it-works.md
@@ -1,31 +1,9 @@
 ---
-title: How It Works
+title: How it works
 ---
 
 ts-node works by registering hooks for `.ts`, `.tsx`, `.js`, and/or `.jsx` extensions.
 
 Vanilla `node` loads `.js` by reading code from disk and executing it.  Our hook runs in the middle, transforming code from TypeScript to JavaScript and passing the result to `node` for execution.  This transformation will respect your `tsconfig.json` as if you had compiled via `tsc`.
 
-`.js` and `.jsx` are only transformed when [`allowJs`](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) is enabled.
-
-`.tsx` and `.jsx` are only transformed when [`jsx`](https://www.typescriptlang.org/docs/handbook/jsx.html) is enabled.
-
-> **Warning:** if a file is ignored or its file extension is not registered, node will either fail to resolve the file or will attempt to execute it as JavaScript without any transformation.  This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features.
-
-> **Warning:** When ts-node is used with `allowJs`, all non-ignored JavaScript files are transformed using the TypeScript compiler.
-
-## Skipping `node_modules`
-
-By default, ts-node avoids compiling files in `/node_modules/` for three reasons:
-
-1. Modules should always be published in a format node.js can consume
-2. Transpiling the entire dependency tree will make your project slower
-3. Differing behaviours between TypeScript and node.js (e.g. ES2015 modules) can result in a project that works until you decide to support a feature natively from node.js
-
-If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](./options#transpilation) or [`TS_NODE_SKIP_IGNORE`](./options#transpilation) to bypass this restriction.
-
-## Skipping pre-compiled TypeScript
-
-If a compiled JavaScript file with the same name as a TypeScript file already exists, the TypeScript file will be ignored.  ts-node will import the pre-compiled JavaScript.
-
-To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](./options#transpilation).
+We also register a few other hooks to apply sourcemaps to stack traces and remap from `.js` imports to `.ts`.
diff --git a/website/docs/options.md b/website/docs/options.md
index 96e49c1eb..726741ad1 100644
--- a/website/docs/options.md
+++ b/website/docs/options.md
@@ -2,64 +2,378 @@
 title: Options
 ---
 
-`ts-node` supports `--print` (`-p`), `--eval` (`-e`), `--require` (`-r`) and `--interactive` (`-i`) similar to the [node.js CLI options](https://nodejs.org/api/cli.html).
-
 All command-line flags support both `--camelCase` and `--hyphen-case`.
 
+Most options can be declared in your tsconfig.json: [Configuration via tsconfig.json](./configuration.md#via-tsconfigjson-recommended)
+
+`ts-node` supports `--print` (`-p`), `--eval` (`-e`), `--require` (`-r`) and `--interactive` (`-i`) similar to the [node.js CLI](https://nodejs.org/api/cli.html).
+
+`ts-node` supports `--project` and `--showConfig` similar to the [tsc CLI](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options).
+
 _Environment variables, where available, are in `ALL_CAPS`_
 
-## Shell
+## CLI Options
+
+### help
+
+```shell
+ts-node --help
+```
+
+Prints the help text
+
+### version
+
+```shell
+ts-node -v
+ts-node -vvv
+```
+
+Prints the version. `-vv` includes node and typescript compiler versions.  `-vvv` includes absolute paths to ts-node and
+typescript installations.
+
+### eval
+
+```shell
+ts-node -e <typescript code>
+# Example
+ts-node -e 'console.log("Hello world!")'
+```
+
+Evaluate code
+
+### print
+
+```shell
+ts-node -p -e <typescript code>
+# Example
+ts-node -p -e '"Hello world!"'
+```
+
+Print result of `--eval`
+
+### interactive
+
+```shell
+ts-node -i
+```
+
+Opens the REPL even if stdin does not appear to be a terminal
+
+### esm
+
+```shell
+ts-node --esm
+ts-node-esm
+```
+
+Bootstrap with the ESM loader, enabling full ESM support
+
+
+## TSConfig Options
+
+### project
+
+```shell
+ts-node -P <path/to/tsconfig>
+```
+
+Path to tsconfig file.
+
+*Environment:* `TS_NODE_PROJECT`
+
+### skipProject
+
+```shell
+ts-node --skipProject
+```
+
+Skip project config resolution and loading
 
--  `-h, --help`   Prints the help text
--  `-v, --version`   Prints the version. `-vv` prints node and typescript compiler versions, too
--  `-e, --eval`   Evaluate code
--  `-p, --print`   Print result of `--eval`
--  `-i, --interactive`   Opens the REPL even if stdin does not appear to be a terminal
--  `--esm`   Bootstrap with the ESM loader, enabling full ESM support
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_SKIP_PROJECT`
 
-## TSConfig
+### cwdMode
 
--  `-P, --project [path]`   Path to TypeScript JSON project file <br/>*Environment:* `TS_NODE_PROJECT`
--  `--skipProject`   Skip project config resolution and loading <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_SKIP_PROJECT`
--  `-c, --cwdMode`   Resolve config relative to the current directory instead of the directory of the entrypoint script
--  `-O, --compilerOptions [opts]`   JSON object to merge with compiler options <br/>*Environment:* `TS_NODE_COMPILER_OPTIONS`
--  `--showConfig`   Print resolved `tsconfig.json`, including `ts-node` options, and exit
+```shell
+ts-node -c
+ts-node --cwdMode
+ts-node-cwd
+```
+
+Resolve config relative to the current directory instead of the directory of the entrypoint script
+
+### compilerOptions
+
+```shell
+ts-node -O <json compilerOptions>
+ts-node --compilerOptions <json compilerOptions>
+```
+
+JSON object to merge with compiler options
+
+*Environment:* `TS_NODE_COMPILER_OPTIONS`
+
+### showConfig
+
+```shell
+ts-node --showConfig
+```
+
+Print resolved `tsconfig.json`, including `ts-node` options, and exit
 
 ## Typechecking
 
--  `-T, --transpileOnly`   Use TypeScript's faster `transpileModule` <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_TRANSPILE_ONLY`
--  `--typeCheck`   Opposite of `--transpileOnly` <br/>*Default:* `true`<br/>*Environment:* `TS_NODE_TYPE_CHECK`
--  `-H, --compilerHost`   Use TypeScript's compiler host API <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_COMPILER_HOST`
--  `--files`   Load `files`, `include` and `exclude` from `tsconfig.json` on startup <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_FILES`
--  `-D, --ignoreDiagnostics [code]`   Ignore TypeScript warnings by diagnostic code <br/>*Environment:* `TS_NODE_IGNORE_DIAGNOSTICS`
+### transpileOnly
+
+```shell
+ts-node -T
+ts-node --transpileOnly
+```
+
+Use TypeScript's faster `transpileModule`
+
+*Default:* `false`<br/>
+*Environment:* `TS_NODE_TRANSPILE_ONLY`
+
+### typeCheck
+
+```shell
+ts-node --typeCheck
+```
+
+Opposite of `--transpileOnly`
+
+*Default:* `true`<br/>
+*Environment:* `TS_NODE_TYPE_CHECK`
+
+### compilerHost
+
+```shell
+ts-node -H
+ts-node --compilerHost
+```
+
+Use TypeScript's compiler host API
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_COMPILER_HOST`
+
+### files
+
+```shell
+ts-node --files
+```
+
+Load `files`, `include` and `exclude` from `tsconfig.json` on startup.  This may
+avoid certain typechecking failures.  See [Missing types](./troubleshooting.md#missing-types) for details.
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_FILES`
+
+### ignoreDiagnostics
+
+```shell
+ts-node -D <code,code>
+ts-node --ignoreDiagnostics <code,code>
+```
+
+Ignore TypeScript warnings by diagnostic code
+
+*Environment:* `TS_NODE_IGNORE_DIAGNOSTICS`
+
+
+## Transpilation Options
+
+### ignore
+
+```shell
+ts-node -I <regexp matching ignored files>
+ts-node --ignore <regexp matching ignored files>
+```
+
+Override the path patterns to skip compilation
+
+*Default:* `/node_modules/` <br/>
+*Environment:* `TS_NODE_IGNORE`
+
+### skipIgnore
+
+```shell
+ts-node --skipIgnore
+```
+
+Skip ignore checks
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_SKIP_IGNORE`
+
+### compiler
+
+```shell
+ts-node -C <name>
+ts-node --compiler <name>
+```
+
+Specify a custom TypeScript compiler
+
+*Default:* `typescript` <br/>
+*Environment:* `TS_NODE_COMPILER`
+
+### swc
+
+```shell
+ts-node --swc
+```
+
+Transpile with [swc](./swc.md).  Implies `--transpileOnly`
+
+*Default:* `false`
+
+### transpiler
+
+```shell
+ts-node --transpiler <name>
+# Example
+ts-node --transpiler ts-node/transpilers/swc
+```
+
+Use a third-party, non-typechecking transpiler
+
+### preferTsExts
+
+```shell
+ts-node --preferTsExts
+```
+
+Re-order file extensions so that TypeScript imports are preferred
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_PREFER_TS_EXTS`
+
+
+## Diagnostic Options
+
+### logError
+
+```shell
+ts-node --logError
+```
+
+Logs TypeScript errors to stderr instead of throwing exceptions
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_LOG_ERROR`
+
+### pretty
+
+```shell
+ts-node --pretty
+```
+
+Use pretty diagnostic formatter
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_PRETTY`
+
+### TS_NODE_DEBUG
+
+```shell
+TS_NODE_DEBUG=true ts-node
+```
+
+Enable debug logging
+
+## Advanced Options
+
+### require
+
+```shell
+ts-node -r <module name or path>
+ts-node --require <module name or path>
+```
+
+Require a node module before execution
+
+### cwd
+
+```shell
+ts-node --cwd <path/to/directory>
+```
+
+Behave as if invoked in this working directory
+
+*Default:* `process.cwd()`<br/>
+*Environment:* `TS_NODE_CWD`
+
+### emit
+
+```shell
+ts-node --emit
+```
+
+Emit output files into `.ts-node` directory. Requires `--compilerHost`
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_EMIT`
+
+### scope
+
+```shell
+ts-node --scope
+```
+
+Scope compiler to files within `scopeDir`.  Anything outside this directory is ignored.
+
+*Default: `false` <br/>
+*Environment:* `TS_NODE_SCOPE`
+
+### scopeDir
+
+```shell
+ts-node --scopeDir <path/to/directory>
+```
+
+Directory within which compiler is limited when `scope` is enabled.
+
+*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.<br/>
+*Environment:* `TS_NODE_SCOPE_DIR`
+
+### moduleTypes
+
+Override the module type of certain files, ignoring the `package.json` `"type"` field.  See [Module type overrides](./module-type-overrides.md) for details.
+
+*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"` <br/>
+*Can only be specified via `tsconfig.json` or API.*
+
+### TS_NODE_HISTORY
+
+```shell
+TS_NODE_HISTORY=<path/to/history/file> ts-node
+```
+
+Path to history file for REPL
+
+*Default:* `~/.ts_node_repl_history`
+
+### noExperimentalReplAwait
 
-## Transpilation
+```shell
+ts-node --noExperimentalReplAwait
+```
 
--  `-I, --ignore [pattern]`   Override the path patterns to skip compilation <br/>*Default:* `/node_modules/` <br/>*Environment:* `TS_NODE_IGNORE`
--  `--skipIgnore`   Skip ignore checks <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_SKIP_IGNORE`
--  `-C, --compiler [name]`   Specify a custom TypeScript compiler <br/>*Default:* `typescript` <br/>*Environment:* `TS_NODE_COMPILER`
--  `--swc`   Transpile with [swc](./transpilers.md#swc).  Implies `--transpileOnly` <br/>*Default:* `false`
--  `--transpiler [name]`   Specify a third-party, non-typechecking transpiler
--  `--preferTsExts`   Re-order file extensions so that TypeScript imports are preferred <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_PREFER_TS_EXTS`
+Disable top-level await in REPL.  Equivalent to node's [`--no-experimental-repl-await`](https://nodejs.org/api/cli.html#cli_no_experimental_repl_await)
 
-## Diagnostics
+*Default:* Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.<br/>
+*Environment:* `TS_NODE_EXPERIMENTAL_REPL_AWAIT` set `false` to disable
 
--  `--logError`   Logs TypeScript errors to stderr instead of throwing exceptions <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_LOG_ERROR`
--  `--pretty`   Use pretty diagnostic formatter <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_PRETTY`
-- `TS_NODE_DEBUG` Enable debug logging<br/>
+### experimentalResolverFeatures
 
-## Advanced
+Enable experimental features that re-map imports and require calls to support: `baseUrl`, `paths`, `rootDirs`, `.js` to `.ts` file extension mappings, `outDir` to `rootDir` mappings for composite projects and monorepos.  For details, see [#1514](https://github.com/TypeStrong/ts-node/issues/1514)
 
--  `-r, --require [path]`   Require a node module before execution
--  `--cwd`   Behave as if invoked in this working directory <br/>*Default:* `process.cwd()`<br/>*Environment:* `TS_NODE_CWD`
--  `--emit`   Emit output files into `.ts-node` directory <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_EMIT`
--  `--scope`  Scope compiler to files within `scopeDir`.  Anything outside this directory is ignored. <br/>*Default: `false` <br/>*Environment:* `TS_NODE_SCOPE`
--  `--scopeDir` Directory within which compiler is limited when `scope` is enabled. <br/>*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.<br/>*Environment:* `TS_NODE_SCOPE_DIR`
--  `moduleTypes`  Override the module type of certain files, ignoring the `package.json` `"type"` field.  See [Module type overrides](./module-type-overrides.md) for details.<br/>*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"` <br/>*Can only be specified via `tsconfig.json` or API.*
-- `TS_NODE_HISTORY` Path to history file for REPL <br/>*Default:* `~/.ts_node_repl_history`<br/>
-- `--noExperimentalReplAwait` Disable top-level await in REPL.  Equivalent to node's [`--no-experimental-repl-await`](https://nodejs.org/api/cli.html#cli_no_experimental_repl_await)<br/>*Default:* Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.<br/>*Environment:* `TS_NODE_EXPERIMENTAL_REPL_AWAIT` set `false` to disable
-- `experimentalResolverFeatures` Enable experimental features that re-map imports and require calls to support: `baseUrl`, `paths`, `rootDirs`, `.js` to `.ts` file extension mappings, `outDir` to `rootDir` mappings for composite projects and monorepos.  For details, see [#1514](https://github.com/TypeStrong/ts-node/issues/1514)<br/>*Default:* `false`<br/>*Can only be specified via `tsconfig.json` or API.*
+*Default:* `false`<br/>
+*Can only be specified via `tsconfig.json` or API.*
 
-## API
+## API Options
 
 The API includes [additional options](https://typestrong.org/ts-node/api/interfaces/RegisterOptions.html) not shown here.
diff --git a/website/docs/performance.md b/website/docs/performance.md
index 69b2c6cba..aebc50def 100644
--- a/website/docs/performance.md
+++ b/website/docs/performance.md
@@ -1,16 +1,16 @@
 ---
-title: Make it fast
+title: Performance
 ---
 
 These tricks will make ts-node faster.
 
 ## Skip typechecking
 
-It is often better to use `tsc --noEmit` to typecheck once before your tests run or as a lint step. In these cases, ts-node can skip typechecking.
+It is often better to use `tsc --noEmit` to typecheck as part of your tests or linting. In these cases, ts-node can skip typechecking.
 
-* Enable [`transpileOnly`](./options.md) to skip typechecking
-* Use our [`swc` integration](./transpilers.md#swc)
+* Enable [swc](./transpilers.md#swc)
   * This is by far the fastest option
+* Enable [`transpileOnly`](./options.md) to skip typechecking without swc
 
 ## With typechecking
 
diff --git a/website/docs/recipes/npx-and-yarn-dlx.md b/website/docs/recipes/npx-and-yarn-dlx.md
new file mode 100644
index 000000000..effff3892
--- /dev/null
+++ b/website/docs/recipes/npx-and-yarn-dlx.md
@@ -0,0 +1,53 @@
+---
+title: npx and yarn dlx
+---
+
+Using [`npx`](https://docs.npmjs.com/cli/v8/commands/npx) or [`yarn dlx`](https://yarnpkg.com/cli/dlx) is a great ways to publish reusable TypeScript tools to GitHub without precompiling or packaging.
+
+Check out our working example: [TypeStrong/ts-node-npx-example](https://github.com/TypeStrong/ts-node-npx-example)
+
+```shell
+npx typestrong/ts-node-npx-example --help
+npx typestrong/ts-node-npx-example --first Arthur --last Dent
+```
+
+TODO publish demo and link to it
+TODO test demo:
+  - uninstall global ts-node
+  - try running demo
+  - does ts-node need to be installed globally?
+
+This boilerplate is a good starting point:
+
+```json title="package.json"
+{
+  "bin": "./cli.ts",
+  "dependencies": {
+    "ts-node": "latest",
+    "@swc/core": "latest",
+    "@swc/helpers": "latest",
+    "@tsconfig/node16": "latest"
+  }
+}
+```
+
+```json title="tsconfig.json"
+{
+  "extends": "@tsconfig/node16/tsconfig.json",
+  "ts-node": {
+    "swc": true
+  }
+}
+```
+
+```typescript twoslash title="cli.ts"
+#!/usr/bin/env ts-node
+
+console.log("Hello world!")
+```
+
+If you require native ESM support, use `ts-node-esm` in your shebang and follow the configuration instructions for ESM: [Native ECMAScript modules](../commonjs-vs-native-ecmascript-modules.md#native-ecmascript-modules)
+
+```typescript twoslash title="cli.ts"
+#!/usr/bin/env ts-node-esm
+```
diff --git a/website/docs/recipes/watching-and-restarting.md b/website/docs/recipes/watching-and-restarting.md
index 82f0d909e..85504b3e9 100644
--- a/website/docs/recipes/watching-and-restarting.md
+++ b/website/docs/recipes/watching-and-restarting.md
@@ -1,7 +1,9 @@
 ---
-title: Watching and Restarting
+title: Watching and restarting
 ---
 
-**TypeScript Node** compiles source code via `require()`, watching files and code reloads are out of scope for the project. If you want to restart the `ts-node` process on file change, existing node.js tools such as [nodemon](https://github.com/remy/nodemon), [onchange](https://github.com/Qard/onchange) and [node-dev](https://github.com/fgnass/node-dev) work.
+ts-node focuses on adding first-class TypeScript support to node.  Watching files and code reloads are out of scope for the project.
 
-There's also [`ts-node-dev`](https://github.com/whitecolor/ts-node-dev), a modified version of [`node-dev`](https://github.com/fgnass/node-dev) using `ts-node` for compilation that will restart the process on file change.
+If you want to restart the `ts-node` process on file change, existing node.js tools such as [nodemon](https://github.com/remy/nodemon), [onchange](https://github.com/Qard/onchange) and [node-dev](https://github.com/fgnass/node-dev) work.
+
+There's also [`ts-node-dev`](https://github.com/whitecolor/ts-node-dev), a modified version of [`node-dev`](https://github.com/fgnass/node-dev) using `ts-node` for compilation that will restart the process on file change. Note that `ts-node-dev` is incompatible with our native ESM loader.
diff --git a/website/docs/scope.md b/website/docs/scope.md
new file mode 100644
index 000000000..4b267821c
--- /dev/null
+++ b/website/docs/scope.md
@@ -0,0 +1,47 @@
+---
+title: Ignored files
+---
+
+ts-node transforms certain files and ignores others.  We refer to this mechanism as "scoping."  There are various
+options to configure scoping, so that ts-node transforms only the files in your project.
+
+> **Warning:**
+>
+> An ignored file can still be executed by node.js.  Ignoring a file means we do not transform it from TypeScript into JavaScript, but it does not prevent execution.
+>
+> If a file requires transformation but is ignored, node may either fail to resolve it or attempt to execute it as vanilla JavaScript.  This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features.
+
+## File extensions
+
+`.js` and `.jsx` are only transformed when [`allowJs`](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) is enabled.
+
+`.tsx` and `.jsx` are only transformed when [`jsx`](https://www.typescriptlang.org/docs/handbook/jsx.html) is enabled.
+
+> **Warning:**
+>
+> When ts-node is used with `allowJs`, _all_ non-ignored JavaScript files are transformed by ts-node.
+
+## Skipping `node_modules`
+
+By default, ts-node avoids compiling files in `/node_modules/` for three reasons:
+
+1. Modules should always be published in a format node.js can consume
+2. Transpiling the entire dependency tree will make your project slower
+3. Differing behaviours between TypeScript and node.js (e.g. ES2015 modules) can result in a project that works until you decide to support a feature natively from node.js
+
+If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](./options#skipignore) or [`TS_NODE_SKIP_IGNORE`](./options#skipignore) to bypass this restriction.
+
+## Skipping pre-compiled TypeScript
+
+If a compiled JavaScript file with the same name as a TypeScript file already exists, the TypeScript file will be ignored.  ts-node will import the pre-compiled JavaScript.
+
+To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](./options#prefertsexts).
+
+## Scope by directory
+
+Our [`scope`](./options.md#scope) and [`scopeDir`](./options.md#scopedir) options will limit transformation to files
+within a directory.
+
+## Ignore by regexp
+
+Our [`ignore`](./options.md#ignore) option will ignore files matching one or more regular expressions.
diff --git a/website/docs/swc.md b/website/docs/swc.md
new file mode 100644
index 000000000..e64646b12
--- /dev/null
+++ b/website/docs/swc.md
@@ -0,0 +1,25 @@
+---
+title: SWC
+---
+
+SWC support is built-in via the `--swc` flag or `"swc": true` tsconfig option.
+
+[SWC](https://swc.rs) is a TypeScript-compatible transpiler implemented in Rust.  This makes it an order of magnitude faster than vanilla `transpileOnly`.
+
+To use it, first install `@swc/core` or `@swc/wasm`.  If using `importHelpers`, also install `@swc/helpers`.  If `target` is less than "es2015" and using `async`/`await` or generator functions, also install `regenerator-runtime`.
+
+```shell
+npm i -D @swc/core @swc/helpers regenerator-runtime
+```
+
+Then add the following to your `tsconfig.json`.
+
+```json title="tsconfig.json"
+{
+  "ts-node": {
+    "swc": true
+  }
+}
+```
+
+> SWC uses `@swc/helpers` instead of `tslib`.  If you have enabled `importHelpers`, you must also install `@swc/helpers`.
diff --git a/website/docs/transpilers.md b/website/docs/transpilers.md
index 6d6f37095..2274bf554 100644
--- a/website/docs/transpilers.md
+++ b/website/docs/transpilers.md
@@ -2,45 +2,20 @@
 title: Transpilers
 ---
 
-In transpile-only mode, we skip typechecking to speed up execution time.  You can go a step further and use a
-third-party transpiler to transform TypeScript into JavaScript even faster.  You will still benefit from
-ts-node's automatic `tsconfig.json` discovery, sourcemap support, and global ts-node CLI.  Integrations
-can automatically derive an appropriate configuration from your existing `tsconfig.json` which simplifies project
-boilerplate.
+ts-node supports third-party transpilers as plugins.  Transpilers such as swc can transform TypeScript into JavaScript
+much faster than the TypeScript compiler.  You will still benefit from ts-node's automatic `tsconfig.json` discovery,
+sourcemap support, and global ts-node CLI. Plugins automatically derive an appropriate configuration from your existing
+`tsconfig.json` which simplifies project boilerplate.
 
 > **What is the difference between a compiler and a transpiler?**
 >
 > For our purposes, a compiler implements TypeScript's API and can perform typechecking.
 > A third-party transpiler does not.  Both transform TypeScript into JavaScript.
 
-## swc
+## Third-party plugins
 
-swc support is built-in via the `--swc` flag or `"swc": true` tsconfig option.
-
-[`swc`](https://swc.rs) is a TypeScript-compatible transpiler implemented in Rust.  This makes it an order of magnitude faster than vanilla `transpileOnly`.
-
-To use it, first install `@swc/core` or `@swc/wasm`.  If using `importHelpers`, also install `@swc/helpers`.  If `target` is less than "es2015" and using either `async`/`await` or generator functions, also install `regenerator-runtime`.
-
-```shell
-npm i -D @swc/core @swc/helpers regenerator-runtime
-```
-
-Then add the following to your `tsconfig.json`.
-
-```json title="tsconfig.json"
-{
-  "ts-node": {
-    "swc": true
-  }
-}
-```
-
-> `swc` uses `@swc/helpers` instead of `tslib`.  If you have enabled `importHelpers`, you must also install `@swc/helpers`.
-
-## Third-party transpilers
-
-The `transpiler` option allows using third-party transpiler integrations with ts-node.  `transpiler` must be given the
-name of a module which can be `require()`d.  The built-in `swc` integration is exposed as `ts-node/transpilers/swc`.
+The `transpiler` option allows using third-party transpiler plugins with ts-node.  `transpiler` must be given the
+name of a module which can be `require()`d.  The built-in `swc` plugin is exposed as `ts-node/transpilers/swc`.
 
 For example, to use a hypothetical "speedy-ts-compiler", first install it into your project: `npm install speedy-ts-compiler`
 
@@ -55,10 +30,14 @@ Then add the following to your tsconfig:
 }
 ```
 
-## Writing your own integration
+## Write your own plugin
+
+To write your own transpiler plugin, check our [API docs](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html).
 
-To write your own transpiler integration, check our [API docs](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html).
+Plugins are `require()`d by ts-node, so they can be a local script or a node module published to npm.  The module must
+export a `create` function described by our
+[`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface.  `create` is
+invoked by ts-node at startup to create one or more transpiler instances.  The instances are used to transform
+TypeScript into JavaScript.
 
-Integrations are `require()`d by ts-node, so they can be published to npm for convenience.  The module must export a `create` function described by our
-[`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface.  `create` is invoked by ts-node
-at startup to create the transpiler.  The transpiler is used repeatedly to transform TypeScript into JavaScript.
+For a working example, check out out our bundled swc plugin: https://github.com/TypeStrong/ts-node/blob/main/src/transpilers/swc.ts
diff --git a/website/docs/troubleshooting.md b/website/docs/troubleshooting.md
index d007bcac4..e80876bf1 100644
--- a/website/docs/troubleshooting.md
+++ b/website/docs/troubleshooting.md
@@ -2,7 +2,7 @@
 title: Troubleshooting
 ---
 
-## Understanding configuration
+## Configuration
 
 ts-node uses sensible default configurations to reduce boilerplate while still respecting `tsconfig.json` if you
 have one.  If you are unsure which configuration is used, you can log it with `ts-node --showConfig`.  This is similar to
@@ -52,7 +52,7 @@ $ ts-node --showConfig
 }
 ```
 
-## Understanding Errors
+## Common errors
 
 It is important to differentiate between errors from ts-node, errors from the TypeScript compiler, and errors from `node`.  It is also important to understand when errors are caused by a type error in your code, a bug in your code, or a flaw in your configuration.
 
@@ -85,3 +85,95 @@ const a = foo?.bar;
 ```
 
 When you try to run this code, node 12 will throw a `SyntaxError`.  To fix this, you must switch to `"target": "es2019"` or lower so TypeScript transforms `?.` into something `node` can understand.
+
+### `ERR_REQUIRE_ESM`
+
+This error is thrown by node when a module is `require()`d, but node believes it should execute as native ESM.  This can happen for a few reasons:
+
+- You have installed an ESM dependency but your own code compiles to CommonJS.
+  - Solution: configure your project to compile and execute as native ESM. [Docs](./commonjs-vs-native-ecmascript-modules.md#native-ecmascript-modules)
+  - Solution: downgrade the dependency to an older, CommonJS version.
+- You have moved your project to ESM but still have a config file, such as `webpack.config.js`, which must be executed as CommonJS
+  - Solution: if supported by the relevant tool, rename your config file to `.cjs`
+  - Solution: Configure a module type override. [Docs](./module-type-overrides.md)
+- You have a mix of CommonJS and native ESM in your project
+  - Solution: double-check all package.json "type" and tsconfig.json "module" configuration [Docs](./commonjs-vs-native-ecmascript-modules.md)
+  - Solution: consider simplifying and switch to all CommonJS or all native ESM
+
+### `ERR_UNKNOWN_FILE_EXTENSION`
+
+This error is thrown by node when a module has an unrecognized file extension, or no extension at all, and is being executed as native ESM.  This can happen for a few reasons:
+
+- You are using a tool which has an extensionless binary, such as `mocha`.
+  - CommonJS supports extensionless files but native ESM does not.
+  - Solution: upgrade to ts-node >=[v10.6.0](https://github.com/TypeStrong/ts-node/releases/tag/v10.6.0), which implements a workaround.
+- Our ESM loader is not installed.
+  - Solution: Use `ts-node-esm`, `ts-node --esm`, or add `"ts-node": {"esm": true}` to your tsconfig.json.  [Docs](./commonjs-vs-native-ecmascript-modules.md#native-ecmascript-modules)
+
+## Missing Types
+
+ts-node does _not_ eagerly load `files`, `include` or `exclude` by default. This is because a large majority of projects do not use all of the files in a project directory (e.g. `Gulpfile.ts`, runtime vs tests) and parsing every file for types slows startup time. Instead, ts-node starts with the script file (e.g. `ts-node index.ts`) and TypeScript resolves dependencies based on imports and references.
+
+Occasionally, this optimization leads to missing types. Fortunately, there are other ways to include them in typechecking.
+
+For global definitions, you can use the `typeRoots` compiler option.  This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types).
+
+Example `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "typeRoots" : ["./node_modules/@types", "./typings"]
+  }
+}
+```
+
+Example project structure:
+
+```text
+<project_root>/
+-- tsconfig.json
+-- typings/
+  -- <module_name>/
+    -- index.d.ts
+```
+
+Example module declaration file:
+
+```typescript twoslash
+declare module '<module_name>' {
+    // module definitions go here
+}
+```
+
+For module definitions, you can use [`paths`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping):
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "custom-module-type": ["types/custom-module-type"]
+    }
+  }
+}
+```
+
+Another option is [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html). This may be helpful if you prefer not to change your `compilerOptions` or structure your type definitions for `typeRoots`. Below is an example of a triple-slash directive as a relative path within your project:
+
+```typescript twoslash
+/// <reference path="./types/lib_greeter" />
+import {Greeter} from "lib_greeter"
+const g = new Greeter();
+g.sayHello();
+```
+
+If none of the above work, and you _must_ use `files`, `include`, or `exclude`, enable our [`files`](./options.md#files) option.
+
+## npx, yarn dlx, and node_modules
+
+When executing TypeScript with `npx` or `yarn dlx`, the code resides within a temporary `node_modules` directory.
+
+The contents of `node_modules` are ignored by default.  If execution fails, enable [`skipIgnore`](./options.md#skipignore).
+
+<!--See also: [npx and yarn dlx](./recipes/npx-and-yarn-dlx.md)-->
diff --git a/website/docs/types.md b/website/docs/types.md
index cb1df0bea..e69de29bb 100644
--- a/website/docs/types.md
+++ b/website/docs/types.md
@@ -1,59 +0,0 @@
----
-title: "Help! My Types Are Missing!"
----
-
-ts-node does _not_ use `files`, `include` or `exclude`, by default. This is because a large majority projects do not use all of the files in a project directory (e.g. `Gulpfile.ts`, runtime vs tests) and parsing every file for types slows startup time. Instead, ts-node starts with the script file (e.g. `ts-node index.ts`) and TypeScript resolves dependencies based on imports and references.
-
-For global definitions, you can use the `typeRoots` compiler option.  This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types).
-
-Example `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "typeRoots" : ["./node_modules/@types", "./typings"]
-  }
-}
-```
-
-Example project structure:
-
-```text
-<project_root>/
--- tsconfig.json
--- typings/
-  -- <module_name>/
-    -- index.d.ts
-```
-
-Example module declaration file:
-
-```typescript twoslash
-declare module '<module_name>' {
-    // module definitions go here
-}
-```
-
-For module definitions, you can use [`paths`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping):
-
-```json title="tsconfig.json"
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "custom-module-type": ["types/custom-module-type"]
-    }
-  }
-}
-```
-
-An alternative approach for definitions of third-party libraries are [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html). This may be helpful if you prefer not to change your TypeScript `compilerOptions` or structure your custom type definitions when using `typeRoots`. Below is an example of the triple-slash directive as a relative path within your project:
-
-```typescript twoslash
-/// <reference path="./types/untyped_js_lib" />
-import {Greeter} from "untyped_js_lib"
-const g = new Greeter();
-g.sayHello();
-```
-
-**Tip:** If you _must_ use `files`, `include`, or `exclude`, enable `--files` flags or set `TS_NODE_FILES=true`.
diff --git a/website/docs/usage.md b/website/docs/usage.md
index 9b62841f8..084c8b396 100644
--- a/website/docs/usage.md
+++ b/website/docs/usage.md
@@ -2,7 +2,7 @@
 title: Usage
 ---
 
-## Shell
+## Command Line
 
 ```shell
 # Execute a script as `node` + `tsc`.
@@ -32,13 +32,17 @@ ts-node-esm script.ts
 
 ## Shebang
 
+To write scripts with maximum portability, [specify options in your `tsconfig.json`](./configuration#via-tsconfigjson-recommended) and omit them from the shebang.
+
 ```typescript twoslash
 #!/usr/bin/env ts-node
 
+// ts-node options are read from tsconfig.json
+
 console.log("Hello, world!")
 ```
 
-Passing options via shebang requires the [`env -S` flag](https://manpages.debian.org/bullseye/coreutils/env.1.en.html#S), which is available on recent versions of `env`. ([compatibility](https://github.com/TypeStrong/ts-node/pull/1448#issuecomment-913895766))
+Including options within the shebang requires the [`env -S` flag](https://manpages.debian.org/bullseye/coreutils/env.1.en.html#S), which is available on recent versions of `env`. ([compatibility](https://github.com/TypeStrong/ts-node/pull/1448#issuecomment-913895766))
 
 ```typescript twoslash
 #!/usr/bin/env -S ts-node --files
@@ -46,26 +50,39 @@ Passing options via shebang requires the [`env -S` flag](https://manpages.debian
 // Technically, Mac allows omitting `-S`, but Linux requires it
 ```
 
-To write scripts with maximum portability, [specify all options in your `tsconfig.json`](./configuration#via-tsconfigjson-recommended) and omit them from the shebang.
+To test your version of `env` for compatibility with `-S`:
 
-```typescript twoslash
-#!/usr/bin/env ts-node
-// This shebang works everywhere
+```shell
+# Note that these unusual quotes are necessary
+/usr/bin/env --debug '-S echo foo bar'
 ```
 
-To test your version of `env` for compatibility:
+## node flags and other tools
+
+You can register ts-node without using our CLI: `node -r ts-node/register` and `node --loader ts-node/esm`
+
+In many cases, setting [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#cli_node_options_options) will enable `ts-node` within other node tools, child processes, and worker threads.  This can be combined with other node flags.
 
 ```shell
-# Note that these unusual quotes are necessary
-/usr/bin/env --debug '-S echo foo bar'
+NODE_OPTIONS="-r ts-node/register --no-warnings" node ./index.ts
 ```
 
-## Programmatic
+Or, if you require native ESM support:
+
+```shell
+NODE_OPTIONS="--loader ts-node/esm"
+```
 
-You can require ts-node and register the loader for future requires by using `require('ts-node').register({ /* options */ })`. You can also use file shortcuts - `node -r ts-node/register` or `node -r ts-node/register/transpile-only` - depending on your preferences.
+This tells any node processes which receive this environment variable to install `ts-node`'s hooks before executing other code.
 
-**Note:** If you need to use advanced node.js CLI arguments (e.g. `--inspect`), use them with `node -r ts-node/register` instead of ts-node's CLI.
+If you are invoking node directly, you can avoid the environment variable and pass those flags to node.
+
+```shell
+node --loader ts-node/esm --inspect ./index.ts
+```
+
+## Programmatic
 
-### Developers
+You can require ts-node and register the loader for future requires by using `require('ts-node').register({ /* options */ })`.
 
-ts-node exports a `create()` function that can be used to initialize a TypeScript compiler that isn't registered to `require.extensions`, and it uses the same code as `register`.
+Check out our [API](./api.md) for more features.
diff --git a/website/scripts/build-readme.mjs b/website/scripts/build-readme.mjs
index 50842776a..2919795de 100755
--- a/website/scripts/build-readme.mjs
+++ b/website/scripts/build-readme.mjs
@@ -100,6 +100,9 @@ async function main() {
         contents: '',
       })
     );
+
+  fs.writeFileSync(readmePath, renderedReadme.contents);
+
   console.error(vfileReporter(renderedReadme));
   if (renderedReadme.messages.length)
     throw new Error('Aborting on diagnostics.');
@@ -109,8 +112,6 @@ async function main() {
     .process(renderedReadme);
   console.error(vfileReporter(lintResults));
   if (lintResults.messages.length) throw new Error('Aborting on diagnostics.');
-
-  fs.writeFileSync(readmePath, renderedReadme.contents);
 }
 
 function parseFrontmatter() {
@@ -134,7 +135,10 @@ function rewritePageLinksToAnchorLinks() {
     visit(ast, 'link', (node) => {
       if (node.url?.match?.(/^https?\:\/\//)) return;
       // TODO take page title into account
-      node.url = node.url.replace(/^[\.\/]*(?:([^#]+)|.*#(.*))$/, '#$1$2');
+      node.url = node.url.replace(
+        /^[\.\/]*(?:recipes\/)?(?:([^#]+)|.*#(.*))$/,
+        '#$1$2'
+      );
       node.url = node.url.replace(/\.md$/, '');
     });
   };
diff --git a/website/sidebars.js b/website/sidebars.js
index 4e3dbd9f5..6e5de11ec 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -10,7 +10,8 @@ module.exports = {
         'usage',
         'configuration',
         'options',
-        'imports',
+        'swc',
+        'commonjs-vs-native-ecmascript-modules',
         'troubleshooting',
         'performance',
       ],
@@ -21,11 +22,12 @@ module.exports = {
       collapsed: false,
       items: [
         'how-it-works',
+        'scope',
         'paths',
-        'types',
         'compilers',
         'transpilers',
         'module-type-overrides',
+        'api',
       ],
     },
     {
@@ -34,6 +36,7 @@ module.exports = {
       collapsed: false,
       items: [
         'recipes/watching-and-restarting',
+        // 'recipes/npx-and-yarn-dlx',
         'recipes/ava',
         'recipes/gulp',
         'recipes/intellij',
diff --git a/website/src/css/custom.css b/website/src/css/custom.css
index 49c27214f..743c1fe8a 100644
--- a/website/src/css/custom.css
+++ b/website/src/css/custom.css
@@ -7,7 +7,7 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  /* Generating by pasting #3178C6, the shade of blue from typescriptlang.org's navbar, into the palette generator at https://v2.docusaurus.io/docs/styling-layout/ */
+  /* Generating by pasting #3178C6, the shade of blue from typescriptlang.org's navbar, into the palette generator at https://docusaurus.io/docs/styling-layout/ */
   --ifm-color-primary: #3178c6;
   --ifm-color-primary-dark: #2c6cb2;
   --ifm-color-primary-darker: #2a66a8;
@@ -27,6 +27,18 @@
   --ifm-code-font-size: 95%; */
 }
 
+[data-theme='dark'] {
+  /* Generating by pasting #4084d0, into the palette generator at https://docusaurus.io/docs/styling-layout/ */
+  --ifm-color-primary: #4084d0;
+  --ifm-color-primary-dark: #3076c4;
+  --ifm-color-primary-darker: #2e70ba;
+  --ifm-color-primary-darkest: #265c99;
+  --ifm-color-primary-light: #5692d5;
+  --ifm-color-primary-lighter: #6199d8;
+  --ifm-color-primary-lightest: #81aee0;
+  --ifm-color-primary-lighter: #4a8bd2;
+}
+
 .docusaurus-highlight-code-line {
   background-color: rgb(72, 77, 91);
   display: block;
diff --git a/website/types/untyped_js_lib.d.ts b/website/types/lib_greeter.ts
similarity index 83%
rename from website/types/untyped_js_lib.d.ts
rename to website/types/lib_greeter.ts
index d6c8f55c6..39d28b1ca 100644
--- a/website/types/untyped_js_lib.d.ts
+++ b/website/types/lib_greeter.ts
@@ -1,4 +1,4 @@
-declare module 'untyped_js_lib' {
+declare module 'lib_greeter' {
   /** API for saying hello to everyone. */
   export class Greeter {
     /** Returns a friendly salutation and a remark about the weather */