New modules docs

packages/documentation/copy/en/modules-reference/Introduction.md

@@ -0,0 +1,15 @@
+---
+title: Modules - Introduction
+short: Introduction
+layout: docs
+permalink: /docs/handbook/modules/introduction.html
+oneline: How TypeScript models JavaScript modules
+translatable: true
+---
+
+This document is divided into four sections:
+
+1. The first section develops the [**theory**](/docs/handbook/modules/theory.html) behind how TypeScript approaches modules. If you want to be able to write the correct module-related compiler options for any situation, reason about how to integrate TypeScript with other tools, or understand how TypeScript processes dependency packages, this is the place to start. While there are guides and reference pages on these topics, building an understanding of these fundamentals will make reading the guides easier, and give you a mental framework for dealing with real-world problems not specifically covered here.
+2. The [**guides**](/docs/handbook/modules/guides/choosing-compiler-options.html) show how to accomplish specific real-world tasks, starting with picking the right compilation settings for a new project. The guides are a good place to start both for beginners who want to get up and running as quickly as possible and for experts who already have a good grasp of the theory but want concrete guidance on a complicated task.
+3. The [**reference**](/docs/handbook/modules/reference.html) section provides a more detailed look at the syntaxes and configurations presented in previous sections.
+4. The [**appendices**](/docs/handbook/modules/appendices/esm-cjs-interop.html) cover complicated topics that deserve additional explanation in more detail than the theory or reference sections allow.

packages/documentation/copy/en/modules-reference/diagrams/README

@@ -0,0 +1,10 @@
+Some of this content uses mermaid diagrams. We could render them as part of the website build with gatsby-remark-mermaid, but that requires puppeteer/Chromium, which has historically caused a lot of cross-platform build issues. These diagrams should not change often, so I’m just going to store the source here and generate the SVGs manually.
+
+Example:
+
+```sh
+npm install -g @mermaid-js/mermaid-cli
+mmdc -i packages/documentation/copy/en/modules-reference/diagrams/esm-cjs-interop.md
+```
+
+declaration-files.svg is a non-Mermaid replacement for theory.md-4.svg. I made it for a talk one time and it’s better than what Mermaid can do with a flowchart.

packages/documentation/copy/en/modules-reference/diagrams/esm-cjs-interop.md

@@ -0,0 +1,26 @@
+```mermaid
+graph TB
+  subgraph Transpiled[ESM transpiled to CJS]
+    direction TB
+    C[Importing module] -- designed based on spec --> D[Imported module]
+  end
+  subgraph ESM
+    direction TB
+    A[Importing module] -- specified behavior --> B[Imported module]
+  end
+```
+
+```mermaid
+graph TD
+  subgraph Transpiled[ESM transpiled to CJS]
+    C[Importing module] -- designed based on spec --> D[Imported module]
+  end
+  subgraph CJS[True CJS]
+    E[Imported module]
+  end
+  subgraph ESM
+    A[Importing module] -- specified behavior --> B[Imported module]
+  end
+  A -. unspecified behavior .-> E
+  C .->|"<span style='font-size: 3em'>❓🤷🏻‍♂️❓</span>"| E
+```