docs: rework structure and improve flat config docs (typescript-eslint#8507)

Author: bradzacher

docs/Developers.mdx

@@ -6,5 +6,7 @@ title: Developers
 These are the developer guides to working with the typescript-eslint tooling.
 It's intended for use by third-parties who want to use our tools to build great things.
 
-> If you're reading this as a new developer: welcome to the community!
-> We're happy to have you! ❤️‍🔥
+:::info Welcome!
+If you're reading this as a new developer: welcome to the community!
+We're happy to have you! ❤️‍🔥
+:::

docs/Packages.mdx

@@ -12,7 +12,7 @@ As of v7 and ESLint 9, most users should be using the **[`typescript-eslint`](./
 It exports configurations for ESLint and brings along the corresponding versions of other packages as dependencies.
 
 :::tip
-See [Getting Started](./Getting_Started.mdx) for guidance on setting up typescript-eslint on a project.
+See [Getting Started](./getting-started/Quickstart.mdx) for guidance on setting up typescript-eslint on a project.
 :::
 
 ## Other Packages

docs/linting/Legacy_ESLint_Setup.mdx renamed to docs/getting-started/Legacy_ESLint_Setup.mdx

@@ -3,13 +3,16 @@ id: legacy-eslint-setup
 title: Legacy ESLint Setup
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 ## Quickstart
 
 These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible.
 
 :::note
 This page is for [ESLint's legacy config format](https://eslint.org/docs/latest/use/configure/configuration-files).
-See [Getting Started](../Getting_Started.mdx) for [ESLint's new "flat" configuration format](https://eslint.org/docs/latest/use/configure/configuration-files-new).
+See [Getting Started](../getting-started/Quickstart.mdx) for [ESLint's new "flat" configuration format](https://eslint.org/docs/latest/use/configure/configuration-files-new).
 :::
 
 ### Step 1: Installation
@@ -83,7 +86,7 @@ ESLint will lint all TypeScript compatible files within the current folder, and
 
 We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit _Typed Rules_ for a setup guide](./Typed_Linting.mdx).
 
-If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](./Troubleshooting.mdx).
+If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
 
 ### Documentation Resources
 

docs/Getting_Started.mdx renamed to docs/getting-started/Quickstart.mdx

@@ -1,28 +1,36 @@
 ---
-id: getting-started
+id: quickstart
 title: Getting Started
+slug: /getting-started/
+pagination_next: getting-started/typed-linting
 ---
 
-## Quickstart
-
-These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible.
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 :::note
-This page is for [ESLint's new "flat" config format](https://eslint.org/docs/latest/use/configure/configuration-files-new).
-See [Legacy ESLint Setup](./linting/Legacy_ESLint_Setup.mdx) for [ESLint's legacy format](https://eslint.org/docs/latest/use/configure/configuration-files).
+This page is a quick-start guide for [ESLint's new "flat" config format](https://eslint.org/docs/latest/use/configure/configuration-files-new) to help you go from zero to linting as quick as possible.
+
+- For the same guide but for [ESLint's legacy format](https://eslint.org/docs/latest/use/configure/configuration-files) — see [Legacy ESLint Setup](./Legacy_ESLint_Setup.mdx).
+- For quickstart information on linting with type information — see [Typed Linting](./Typed_Linting.mdx).
+
 :::
 
+## Quickstart
+
+These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible.
+
 ### Step 1: Installation
 
-First, install the required packages for [ESLint](https://eslint.org), [TypeScript](https://typescriptlang.org), and this plugin:
+First, install the required packages for [ESLint](https://eslint.org), [TypeScript](https://typescriptlang.org), and [our tooling](../packages/TypeScript_ESLint.mdx):
 
 ```bash npm2yarn
 npm install --save-dev eslint typescript typescript-eslint
 ```
 
 ### Step 2: Configuration
 
-Next, create a `eslint.config.js` config file in the root of your project, and populate it with the following:
+Next, create an `eslint.config.js` config file in the root of your project, and populate it with the following:
 
 ```js title="eslint.config.js"
 // @ts-check
@@ -36,6 +44,8 @@ export default tseslint.config(
 );
 ```
 
+This code will enable our [recommended configuration](../users/Shared_Configurations.mdx) for linting.
+
 ### Step 3: Running ESLint
 
 Open a terminal to the root of your project and run the following command:
@@ -68,19 +78,19 @@ ESLint will lint all TypeScript compatible files within the current folder, and
 
 ## Details
 
-The [`config`](./packages/TypeScript_ESLint.mdx) helper sets three parts of ESLint:
-
-- [Parser](https://eslint.org/docs/latest/use/configure/parser): set to [`@typescript-eslint/parser`](./packages/Parser.mdx) so ESLint knows how to parse the new pieces of TypeScript syntax.
-- [Plugins](https://eslint.org/docs/latest/use/configure/plugins): set to [`@typescript-eslint/eslint-plugin`](./packages/ESLint_Plugin.mdx) to load [rules listed in our _Rules_ page](/rules).
-- [Rules](https://eslint.org/docs/latest/use/configure/rules): extends from our [recommended configuration](./linting/Configurations.mdx#recommended) to enable our most commonly useful lint rules.
+- `tseslint.config(...)` is an _optional_ helper function — [read more about it here](../packages/TypeScript_ESLint.mdx#config).
+- `'@eslint/js'` / `eslint.configs.recommended` turns on [eslint's recommended config](https://www.npmjs.com/package/@eslint/js).
+- `...tseslint.configs.recommended` turns on [our recommended config](../users/Shared_Configurations.mdx#recommended).
 
-See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files) for more details on configuring ESLint.
+See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files-new) for more details on configuring ESLint.
 
 ## Next Steps
 
-We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit the next page for a setup guide](./linting/Typed_Linting.mdx 'Visit the next page for a typed rules setup guide').
+We provide a plethora of powerful rules that utilize the power of TypeScript's type information.
+
+[Visit the next page for a setup guide](./Typed_Linting.mdx 'Visit the next page for a typed rules setup guide').
 
-If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](./linting/Troubleshooting.mdx).
+If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
 
 ### Documentation Resources
 

docs/linting/Typed_Linting.mdx renamed to docs/getting-started/Typed_Linting.mdx

@@ -1,6 +1,7 @@
 ---
 id: typed-linting
 title: Linting with Type Information
+pagination_next: getting-started/typed-linting/monorepos
 ---
 
 import Tabs from '@theme/Tabs';
@@ -38,7 +39,7 @@ For CommonJS modules and/or older versions of Node.js, [use `__dirname` or an al
 
 In more detail:
 
-- `tseslint.configs.recommendedTypeChecked` is another [recommended configuration](./Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
+- `tseslint.configs.recommendedTypeChecked` is another [recommended configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
 - `parserOption.project` tells our parser how to find the TSConfig for each source file (`true` indicates to find the closest `tsconfig.json` for each source file)
   - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
 
@@ -69,7 +70,7 @@ module.exports = {
 
 In more detail:
 
-- `plugin:@typescript-eslint/recommended-type-checked` is another [recommended configuration](./Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
+- `plugin:@typescript-eslint/recommended-type-checked` is another [recommended configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
 - `parserOptions.project` tells our parser how to find the TSConfig for each source file (`true` indicates to find the closest `tsconfig.json` for each source file)
   - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
 - `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigrootdir)).
@@ -79,7 +80,7 @@ In more detail:
 
 :::caution
 Your ESLint config file may start receiving a parsing error about type information.
-See [our TSConfig inclusion FAQ](./Troubleshooting.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file).
+See [our TSConfig inclusion FAQ](../troubleshooting/FAQ.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file).
 :::
 
 With that done, run the same lint command you ran before.
@@ -137,7 +138,7 @@ If your project is a multi-package monorepo, see [our docs on configuring a mono
 
 ### How can I disable type-aware linting for a subset of files?
 
-You can combine ESLint's [overrides](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns) config in conjunction with our [`disable-type-checked`](./Configurations.mdx#disable-type-checked) config to turn off type-aware linting on specific subsets of files.
+You can combine ESLint's [overrides](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns) config in conjunction with our [`disable-type-checked`](../users/Shared_Configurations.mdx#disable-type-checked) config to turn off type-aware linting on specific subsets of files.
 
 <Tabs groupId="eslint-config">
 <TabItem value="Flat Config">
@@ -211,8 +212,8 @@ This means that generally they usually only run a complete lint before a push, o
 ### I get errors telling me "The file must be included in at least one of the projects provided"
 
 You're using an outdated version of `@typescript-eslint/parser`.
-Update to the latest version to see a more informative version of this error message, explained in our [Troubleshooting and FAQs page](./Troubleshooting.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file).
+Update to the latest version to see a more informative version of this error message, explained in our [Troubleshooting and FAQs page](../troubleshooting/FAQ.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file).
 
 ## Troubleshooting
 
-If you're having problems getting this working, please have a look at our [Troubleshooting and FAQs page](./Troubleshooting.mdx).
+If you're having problems getting this working, please have a look at our [Troubleshooting and FAQs page](../troubleshooting/FAQ.mdx).

docs/linting/typed-linting/Monorepos.mdx renamed to docs/getting-started/typed-linting/Monorepos.mdx

@@ -1,6 +1,7 @@
 ---
 id: monorepos
 title: Monorepo Configuration
+pagination_next: null
 ---
 
 import Tabs from '@theme/Tabs';
@@ -158,4 +159,4 @@ As an interim workaround, consider one of the following:
 
 ## Troubleshooting
 
-If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../Troubleshooting.mdx).
+If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../../troubleshooting/FAQ.mdx).

docs/maintenance/Issues.mdx

@@ -141,7 +141,7 @@ We avoid features that:
 - Are only relevant for a minority of users, as they aren't likely worth the maintenance burden
 - Aren't TypeScript-specific (e.g. should be in ESLint core instead)
 - Are only relevant with specific userland frameworks or libraries, such as Jest or React
-- Are for "formatting" functionality (we [strongly recommend users use a separate dedicated formatter](../linting/troubleshooting/Formatting.mdx))
+- Are for "formatting" functionality (we [strongly recommend users use a separate dedicated formatter](../troubleshooting/Formatting.mdx))
 
 #### ✨ Rule Enhancements
 

docs/maintenance/Team.mdx

@@ -94,5 +94,5 @@ We're eternally grateful to every individual and organization able to help us ke
 
 See [`.github/SPONSORSHIPS.md`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/SPONSORSHIPS.md) for documentation on how and why to sponsor us.
 
-You can find our biggest sponsors on [typescript-eslint.io > Financial Contributors](https://typescript-eslint.io/#financial-contributors).
+You can find our biggest sponsors on [typescript-eslint.io > Financial Contributors](/#financial-contributors).
 More can be found on [our Open Collective](https://opencollective.com/typescript-eslint).

docs/packages/ESLint_Plugin.mdx

@@ -8,7 +8,7 @@ sidebar_label: eslint-plugin
 > The TypeScript plugin for ESLint. ✨
 
 :::info
-See [Getting Started](../Getting_Started.mdx) for documentation on how to lint your TypeScript code with ESLint.
+See [Getting Started](../getting-started/Quickstart.mdx) for documentation on how to lint your TypeScript code with ESLint.
 :::
 
 `@typescript-eslint/eslint-plugin` is an ESLint plugin used to load in custom rules and rule configurations lists from typescript-eslint.

docs/packages/ESLint_Plugin_TSLint.mdx

@@ -8,8 +8,8 @@ sidebar_label: eslint-plugin-tslint
 > ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. ✨
 
 :::caution
-Per [What About TSLint?](../linting/troubleshooting/TSLint.mdx), we highly recommend migrating off TSLint.
-See [Getting Started](../Getting_Started.mdx) for documentation on how to lint your TypeScript code with ESLint.
+Per [What About TSLint?](../troubleshooting/TSLint.mdx), we highly recommend migrating off TSLint.
+See [Getting Started](../getting-started/Quickstart.mdx) for documentation on how to lint your TypeScript code with ESLint.
 :::
 
 ## Installation

docs/packages/Parser.mdx

@@ -60,7 +60,7 @@ interface ParserOptions {
 
 Whether to use common heuristics to infer whether ESLint is being used as part of a single run (as opposed to `--fix` mode or in a persistent session such as an editor extension).
 
-When typescript-eslint handles TypeScript Program management behind the scenes for [linting with type information](../linting/Typed_Linting.mdx), this distinction is important for performance.
+When typescript-eslint handles TypeScript Program management behind the scenes for [linting with type information](../getting-started/Typed_Linting.mdx), this distinction is important for performance.
 There is significant overhead to managing TypeScript "Watch" Programs needed for the long-running use-case.
 Being able to assume the single run case allows typescript-eslint to faster immutable Programs instead.
 
@@ -126,7 +126,7 @@ Specifies the version of ECMAScript syntax you want to use. This is used by the
 
 > Default `undefined`.
 
-This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](../linting/Typed_Linting.mdx). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster.
+This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](../getting-started/Typed_Linting.mdx). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster.
 
 ### `extraFileExtensions`