microsoft · orta · Mar 4, 2021 · Mar 2, 2021 · Mar 3, 2021 · Mar 4, 2021
diff --git a/README.md b/README.md
@@ -128,7 +128,7 @@ A template for generating a new playground plugin which you can use via `npm ini
 
 ## Handbook Epub
 
-Generates an epub file from the handbook files. You can try downloading it at http://www.staging-typescript.org/assets/typescript-handbook-beta.epub
+Generates an epub file from the handbook files. You can try downloading it at http://www.typescriptlang.org/assets/typescript-handbook.epub
 
 ## Community Meta
 

diff --git a/docs/New TypeScript Version.md b/docs/New TypeScript Version.md
@@ -49,6 +49,10 @@ For each new flag:
   - Linking compiler versions
   - Add a new section to `releaseToConfigsMap` for your version
 
+#### Playground
+
+The tag should be automatically generated on a [daily basis](https://github.com/microsoft/TypeScript-Make-Monaco-Builds/actions/workflows/nightly_check_prod_deploys.yml) - so you shouldn't have to do anything
+
 ##### Tests
 
 Run `yarn test`.
@@ -62,11 +66,24 @@ Unless something drastic has change, you shouldn't need to do anything. You coul
 
 ### Release
 
-#### Playground
+#### Release Notes
+
+Grab the markdown from the [blog posts repo](https://github.com/microsoft/TypeScript-blog-posts), create a file like: `packages/documentation/copy/en/release-notes/TypeScript 3.9.md`
+
+Grab the header info from a previous release notes, and add it to your new version:
+
+```md
+---
+title: TypeScript 3.9
+layout: docs
+permalink: /docs/handbook/release-notes/typescript-3-9.html
+oneline: TypeScript 3.9 Release Notes
+---
+```
 
-Make a tag for the final version in [`orta/make-monaco-builds`](https://github.com/orta/make-monaco-builds/) e.g. `git tag 3.9.3` and push it up.
+You can add twoslash to the code samples if you want.
 
-Remove the link to the beta in the dropdowns in: [`packages/playground/src/index.ts`](https://github.com/microsoft/TypeScript-website/blob/v2/packages/playground/src/index.ts) because it will be auto-generated now.
+When you're happy with that, then edit [`packages/documentation/copy/en/release-notes/Overview.md](https://github.com/microsoft/TypeScript-website/blob/v2/packages/documentation/copy/en/release-notes/Overview.md) to include the changes you just added, and simplify descriptions.
 
 ##### Index
 

diff --git a/packages/documentation/copy/en/handbook-v1/Basic Types.md b/packages/documentation/copy/en/handbook-v1/Basic Types.md
@@ -2,8 +2,9 @@
 title: Basic Types
 layout: docs
 permalink: /docs/handbook/basic-types.html
-oneline: "Step one in learning TypeScript: The basic types."
+oneline: "Step two in learning TypeScript: The basic types."
 handbook: "true"
+deprecated_by: /docs/handbook/2/everyday-types.html
 ---
 
 For programs to be useful, we need to be able to work with some of the simplest units of data: numbers, strings, structures, boolean values, and the like.

diff --git a/packages/documentation/copy/en/handbook-v1/Classes.md b/packages/documentation/copy/en/handbook-v1/Classes.md
@@ -4,6 +4,7 @@ layout: docs
 permalink: /docs/handbook/classes.html
 oneline: How classes work in TypeScript
 handbook: "true"
+deprecated_by: /docs/handbook/2/classes.html
 ---
 
 Traditional JavaScript uses functions and prototype-based inheritance to build up reusable components, but this may feel a bit awkward to programmers more comfortable with an object-oriented approach, where classes inherit functionality and objects are built from these classes.

diff --git a/packages/documentation/copy/en/handbook-v1/Functions.md b/packages/documentation/copy/en/handbook-v1/Functions.md
@@ -4,6 +4,7 @@ layout: docs
 permalink: /docs/handbook/functions.html
 oneline: How to add types to a function
 handbook: "true"
+deprecated_by: /docs/handbook/2/functions.html
 ---
 
 Functions are the fundamental building block of any application in JavaScript.

diff --git a/packages/documentation/copy/en/handbook-v1/Generics.md b/packages/documentation/copy/en/handbook-v1/Generics.md
@@ -4,6 +4,7 @@ layout: docs
 permalink: /docs/handbook/generics.html
 oneline: Introduction to TypeScript and Generics
 handbook: "true"
+deprecated_by: /docs/handbook/2/generics.html
 ---
 
 A major part of software engineering is building components that not only have well-defined and consistent APIs, but are also reusable.

diff --git a/packages/documentation/copy/en/handbook-v1/Interfaces.md b/packages/documentation/copy/en/handbook-v1/Interfaces.md
@@ -4,6 +4,7 @@ layout: docs
 permalink: /docs/handbook/interfaces.html
 oneline: How to write an interface with TypeScript
 handbook: "true"
+deprecated_by: /docs/handbook/2/objects.html
 ---
 
 One of TypeScript's core principles is that type checking focuses on the _shape_ that values have.

diff --git a/packages/documentation/copy/en/handbook-v1/Literal Types.md b/packages/documentation/copy/en/handbook-v1/Literal Types.md
@@ -4,6 +4,7 @@ layout: docs
 permalink: /docs/handbook/literal-types.html
 oneline: Using literal types with TypeScript
 handbook: "true"
+deprecated_by: /docs/handbook/2/everyday-types.html#literal-types
 ---
 
 A literal is a more concrete sub-type of a collective type.

diff --git a/packages/documentation/copy/en/handbook-v1/Unions and Intersections.md b/packages/documentation/copy/en/handbook-v1/Unions and Intersections.md
@@ -4,6 +4,7 @@ layout: docs
 permalink: /docs/handbook/unions-and-intersections.html
 oneline: How to use unions and intersection types in TypeScript
 handbook: "true"
+deprecated_by: /docs/handbook/2/everyday-types.html#union-types
 ---
 
 So far, the handbook has covered types which are atomic objects.

diff --git a/packages/documentation/copy/en/handbook-v2/Basics.md b/packages/documentation/copy/en/handbook-v2/Basics.md
@@ -5,8 +5,6 @@ permalink: /docs/handbook/2/basic-types.html
 oneline: "Step one in learning TypeScript: The basic types."
 preamble: >
   <p>Welcome to the first page of the handbook, if this is your first experience with TypeScript - you may want to start at one of the '<a href='https://www.typescriptlang.org/docs/handbook/intro.html#get-started'>Getting Started</a>' guides</a>
-
-beta: true
 ---
 
 Each and every value in JavaScript has a set of behaviors you can observe from running different operations.

diff --git a/packages/documentation/copy/en/handbook-v2/Classes.md b/packages/documentation/copy/en/handbook-v2/Classes.md
@@ -3,7 +3,6 @@ title: Classes
 layout: docs
 permalink: /docs/handbook/2/classes.html
 oneline: "How classes work in TypeScript"
-beta: true
 ---
 
 <blockquote class='bg-reading'>
@@ -127,7 +126,11 @@ g.name = "also not ok";
 
 ### Constructors
 
-[Background Reading: Constructor (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/constructor)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/constructor'>Constructor (MDN)</a><br/>
+   </p>
+</blockquote>
 
 Class constructors are very similar to functions.
 You can add parameters with type annotations, default values, and overloads:
@@ -184,7 +187,11 @@ Forgetting to call `super` is an easy mistake to make in JavaScript, but TypeScr
 
 ### Methods
 
-> [Background Reading: Method definitions (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions'>Method definitions</a><br/>
+   </p>
+</blockquote>
 
 A function property on a class is called a _method_.
 Methods can use all the same type annotations as functions and constructors:
@@ -337,7 +344,11 @@ c.y = 10;
 
 ### `extends` Clauses
 
-> [Background Reading: extends keyword (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends'>extends keyword (MDN)</a><br/>
+   </p>
+</blockquote>
 
 Classes may `extend` from a base class.
 A derived class has all the properties and methods of its base class, and also define additional members.
@@ -366,7 +377,11 @@ d.woof(3);
 
 #### Overriding Methods
 
-> [Background reading: super keyword (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/super)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/super'>super keyword (MDN)</a><br/>
+   </p>
+</blockquote>
 
 A derived class can also override a base class field or property.
 You can use the `super.` syntax to access base class methods.
@@ -709,7 +724,11 @@ If you need to protect values in your class from malicious actors, you should us
 
 ## Static Members
 
-> [Background Reading: Static Members (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static'>Static Members (MDN)</a><br/>
+   </p>
+</blockquote>
 
 Classes may have `static` members.
 These members aren't associated with a particular instance of the class.
@@ -823,7 +842,11 @@ The `static` members of a generic class can never refer to the class's type para
 
 ## `this` at Runtime in Classes
 
-> [Background Reading: `this` keyword (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this'>this keyword (MDN)</a><br/>
+   </p>
+</blockquote>
 
 It's important to remember that TypeScript doesn't change the runtime behavior of JavaScript, and that JavaScript is somewhat famous for having some peculiar runtime behaviors.
 
@@ -854,7 +877,11 @@ TypeScript provides some ways to mitigate or prevent this kind of error.
 
 ### Arrow Functions
 
-> [Background Reading: Arrow functions (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions'>Arrow functions (MDN)</a><br/>
+   </p>
+</blockquote>
 
 If you have a function that will often be called in a way that loses its `this` context, it can make sense to use an arrow function property instead of a method definition:
 
@@ -1020,7 +1047,11 @@ console.log(a.z);
 
 ## Class Expressions
 
-> [Background reading: Class expressions (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/class)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/class'>Class expressions (MDN)</a><br/>
+   </p>
+</blockquote>
 
 Class expressions are very similar to class declarations.
 The only real difference is that class expressions don't need a name, though we can refer to them via whatever identifier they ended up bound to:

diff --git a/packages/documentation/copy/en/handbook-v2/Everyday Types.md b/packages/documentation/copy/en/handbook-v2/Everyday Types.md
@@ -3,11 +3,8 @@ title: Everyday Types
 layout: docs
 permalink: /docs/handbook/2/everyday-types.html
 oneline: "The language primitives."
-beta: true
 ---
 
-<!-- Extremely WIP, do not review -->
-
 In this chapter, we'll cover some of the most common types of values you'll find in JavaScript code, and explain the corresponding ways to describe those types in TypeScript.
 This isn't an exhaustive list, and future chapters will describe more ways to name and use other types.
 
@@ -384,7 +381,74 @@ Being concerned only with the structure and capabilities of types is why we call
 ### Differences Between Type Aliases and Interfaces
 
 Type aliases and interfaces are very similar, and in many cases you can choose between them freely.
-Here are the most relevant differences between the two that you should be aware of.
+Almost all features of an `interface` are available in `type`, the key distinction is that a type cannot be re-opened to add new properties vs an interface which is always extendable.
+
+<table class='full-width-table'>
+  <tbody>
+    <tr>
+      <th><code>Interface</code></th>
+      <th><code>Type</code></th>
+    </tr>
+    <tr>
+      <td>
+        <p>Extending an interface</p>
+        <code><pre>
+interface Animal {
+  name: string
+}<br/>
+interface Bear extends Animal {
+  honey: boolean
+}<br/>
+const bear = getBear() 
+bear.name
+bear.honey
+        </pre></code>
+      </td>
+      <td>
+        <p>Extending a type via intersections</p>
+        <code><pre>
+type Animal = {
+  name: string
+}<br/>
+type Bear = Animal & { 
+  honey: Boolean 
+}<br/>
+const bear = getBear();
+bear.name;
+bear.honey;
+        </pre></code>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p>Adding new fields to an existing interface</p>
+        <code><pre>
+interface Window {
+  title: string
+}<br/>
+interface Window {
+  ts: TypeScriptAPI
+}<br/>
+const src = 'const a = "Hello World"';
+window.ts.transpileModule(src, {});
+        </pre></code>
+      </td>
+      <td>
+        <p>A type cannot be changed after being created</p>
+        <code><pre>
+type Window = {
+  title: string
+}<br/>
+type Window = {
+  ts: TypeScriptAPI
+}<br/>
+<span style="color: #A31515"> // Error: Duplicate identifier 'Window'.</span><br/>
+        </pre></code>
+      </td>
+    </tr>
+    </tbody>
+</table>
+
 You'll learn more about these concepts in later chapters, so don't worry if you don't understand all of these right away.
 
 - Type alias names [_may_ appear in error messages](/play?#code/PTAEGEHsFsAcEsA2BTATqNrLusgzngIYDm+oA7koqIYuYQJ56gCueyoAUCKAC4AWHAHaFcoSADMaQ0PCG80EwgGNkALk6c5C1EtWgAsqOi1QAb06groEbjWg8vVHOKcAvpokshy3vEgyyMr8kEbQJogAFND2YREAlOaW1soBeJAoAHSIkMTRmbbI8e6aPMiZxJmgACqCGKhY6ABGyDnkFFQ0dIzMbBwCwqIccabcYLyQoKjIEmh8kwN8DLAc5PzwwbLMyAAeK77IACYaQSEjUWZWhfYAjABMAMwALA+gbsVjoADqgjKESytQPxCHghAByXigYgBfr8LAsYj8aQMUASbDQcRSExCeCwFiIQh+AKfAYyBiQFgOPyIaikSGLQo0Zj-aazaY+dSaXjLDgAGXgAC9CKhDqAALxJaw2Ib2RzOISuDycLw+ImBYKQflCkWRRD2LXCw6JCxS1JCdJZHJ5RAFIbFJU8ADKC3WzEcnVZaGYE1ABpFnFOmsFhsil2uoHuzwArO9SmAAEIsSFrZB-GgAjjA5gtVN8VCEc1o1C4Q4AGlR2AwO1EsBQoAAbvB-gJ4HhPgB5aDwem-Ph1TCV3AEEirTp4ELtRbTPD4vwKjOfAuioSQHuDXBcnmgACC+eCONFEs73YAPGGZVT5cRyyhiHh7AAON7lsG3vBggB8XGV3l8-nVISOgghxoLq9i7io-AHsayRWGaFrlFauq2rg9qaIGQHwCBqChtKdgRo8TxRjeyB3o+7xAA), sometimes in place of the equivalent anonymous type (which may or may not be desirable). Interfaces will always be named in error messages.
@@ -604,6 +668,10 @@ function liveDangerously(x?: number | undefined) {
 
 Just like other type assertions, this doesn't change the runtime behavior of your code, so it's important to only use `!` when you know that the value _can't_ be `null` or `undefined`.
 
+### Enums
+
+Enums are a feature added to JavaScript by TypeScript which allows for describing a value which could be one of a set of possible named constants. Unlike most TypeScript features, this is _not_ a type-level addition to JavaScript but something added to the language and runtime. Because of this, it's a feature which you should know exists, but maybe hold off on using unless you are sure. You can read more about enums in the [Enum reference page](/docs/handbook/enums.html).
+
 ### Less Common Primitives
 
 It's worth mentioning the rest of the primitives in JavaScript which are represented in the type system.

diff --git a/packages/documentation/copy/en/handbook-v2/Modules.md b/packages/documentation/copy/en/handbook-v2/Modules.md
@@ -3,7 +3,6 @@ title: Modules
 layout: docs
 permalink: /docs/handbook/2/modules.html
 oneline: "How JavaScript handles communicating across file boundaries."
-beta: true
 ---
 
 JavaScript has a long history of different ways to handle modularizing code.

diff --git a/packages/documentation/copy/en/handbook-v2/More on Functions.md b/packages/documentation/copy/en/handbook-v2/More on Functions.md
@@ -3,7 +3,6 @@ title: More on Functions
 layout: docs
 permalink: /docs/handbook/2/functions.html
 oneline: "Learn about how Functions work in TypeScript."
-beta: true
 ---
 
 Functions are the basic building block of any application, whether they're local functions, imported from another module, or methods on a class.
@@ -698,7 +697,12 @@ If need to accept an arbitrary function but don't intend to call it, the type `(
 
 ## Rest Parameters and Arguments
 
-**Background reading**: [Rest Parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) and [Spread Syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax)
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters'>Rest Parameters</a><br/>
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax'>Spread Syntax</a><br/>
+   </p>
+</blockquote>
 
 ### Rest Parameters
 
@@ -753,7 +757,12 @@ Using rest arguments may require turning on [`downlevelIteration`](/tsconfig/#do
 
 ## Parameter Destructuring
 
-> **Background reading**: [Destructuring Assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)
+
+<blockquote class='bg-reading'>
+   <p>Background Reading:<br />
+   <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment'>Destructuring Assignment</a><br/>
+   </p>
+</blockquote>
 
 You can use parameter destructuring to conveniently unpack objects provided as an argument into one or more local variables in the function body.
 In JavaScript, it looks like this: