Create the Redux Essentials page, take 2 (reduxjs#3740)

markerikson · web-flow · commit 35b5bcfb9867 · 2020-07-13T09:44:00.000-04:00
* Port admonition and code block CSS from RTK site * Restructure sidebars to add "Tutorials" section * Add empty "Quick Start" tutorial page * Bump Docusaurus to alpha.48 * Fix text color in admonitions * Add blockquote styling for other pages * Add DetailedExplanation component * Initial Quick Start intro content * Quick Start: add "What is Redux" and "Terms" sections * Quick Start: add "play with app" content * Quick Start: create nested folder and rename file * Store setup * Quick Start: add slice, reducer, immutability, and thunk sections * Quick start: Add React-Redux section * Quick start: emphasize immutability, highlight JSX * Tweak "know more?" and explanation styles * Fix typo and add thunk usage mention * Bump Docusaurus to alpha.50 * Temporarily rename files to .md to work around DS bug See facebook/docusaurus#2551 * Add border color for highlight lines * Add code block titles and test line highlights * Initial project setup section * Add reducer and data flow explanations * Tweak wording * Link example repo and sandbox * Update Docusaurus * Fill out "Basic Data Flow" page * Add additional phrasing * Add intro and summary content for part 3 * Shrink code block file header padding * Finish writing Part 3 * Link to Immer docs * Add initial Part 4 content * Finish Quick Start part 4 * Remove unnecessary uses of "just" * Add Part 5 outline * Update page titles * Half of part 5 * Finish Quick Start content. Yay!!!!!! * Clean up tutorial part 1 based on review feedback - Reworded several explanations - Added "Immutability" section under "concepts" - Added data flow diagram - Removed leftover example code block * Add "What You've Learned" to part 1 * Rename part 5 -> 6 * Rename part 4 -> 5 * Rename part 3 -> 4 * Rename part 2 -> 3 * Add new Part 2 * Fix up TODO comments and broken links * Swap to new dataflow diagram * Assorted edits and link fixes * Rename "Quick Start" to "Redux Essentials" * Fix links and rename images * Update example app repo/sandbox links * Clarify random seed behavior * Rework introduction content - Redid "Getting Started" page by moving RTK first and removing most of the external tutorial links, - Added RTK to "Installation" page - Added description and "Best Practices" phrase to style guide - Added external links to prereq concepts - Fixed one-way data flow image - Added "Tutorial" link to header/footer, pointing to Essentials * Remove unwanted colors from pagination buttons * Emphasize recommended tutorial * Clean up README * Fix PR preview redirect * Clarify "smallest amount" wording * Try to fix redirects Former-commit-id: af8c8ea
diff --git a/README.md.REMOVED.git-id b/README.md.REMOVED.git-id
@@ -1 +1 @@
-c6206af164afffc7f7cc75f060a2329fcb8d213c
+06c2c8fd1f8d1d3e11232d26f91223eccec1d8f3
diff --git a/docs/components/DetailedExplanation.jsx b/docs/components/DetailedExplanation.jsx
@@ -0,0 +1,15 @@
+import React from 'react'
+
+export const DetailedExplanation = ({
+  children,
+  title = 'Detailed Explanation'
+}) => {
+  return (
+    <details className="detailed-explanation">
+      <summary>
+        <h4>{title}</h4>
+      </summary>
+      {children}
+    </details>
+  )
+}
diff --git a/docs/introduction/GettingStarted.md.REMOVED.git-id b/docs/introduction/GettingStarted.md.REMOVED.git-id
@@ -1 +1 @@
-c1009f22843241280a4c6e9a9064536491e11266
+73670ac005460e36ca5978f3a82499a22bffc84a
diff --git a/docs/introduction/Installation.md b/docs/introduction/Installation.md
@@ -7,13 +7,33 @@ hide_title: true
 
 # Installation
 
+## Redux Toolkit
+
+Redux Toolkit includes the Redux core, as well as other key packages we feel are essential for building Redux applications (such as Redux Thunk and Reselect).
+
+It's available as a package on NPM for use with a module bundler or in a Node application:
+
+```bash
+# NPM
+npm install @reduxjs/toolkit
+
+# Yarn
+yarn add @reduxjs/toolkit
+```
+
+It's also available as a UMD build, which can be loaded from [the `dist` folder on unpkg](https://unpkg.com/@reduxjs/toolkit/dist/). The UMD builds make Redux Toolkit available as a `window.RTK` global variable.
+
+## Redux Core
+
 To install the stable version:
 
 ```bash
+# NPM
 npm install redux
-```
 
-This assumes you are using [npm](https://www.npmjs.com/) as your package manager.
+# Yarn
+yarn add redux
+```
 
 If you're not, you can [access these files on unpkg](https://unpkg.com/redux/), download them, or point your package manager to them.
 
diff --git a/docs/style-guide/style-guide.md.REMOVED.git-id b/docs/style-guide/style-guide.md.REMOVED.git-id
@@ -1 +1 @@
-a0c4ec513de343fe7c98730e3b0fdd21b4b088ef
+d626d6f8aad44259d58ad4e5ade603beaa539c1d
diff --git a/docs/tutorials/essentials/part-1-overview-concepts.md.REMOVED.git-id b/docs/tutorials/essentials/part-1-overview-concepts.md.REMOVED.git-id
@@ -0,0 +1 @@
+a4df5f1f297652579e324e960d423e8e9faccb7d
diff --git a/docs/tutorials/essentials/part-2-app-structure.md.REMOVED.git-id b/docs/tutorials/essentials/part-2-app-structure.md.REMOVED.git-id
@@ -0,0 +1 @@
+4ad20f607ad7d35a63efbfa3bf75682b9f12f83a
diff --git a/docs/tutorials/essentials/part-3-data-flow.md.REMOVED.git-id b/docs/tutorials/essentials/part-3-data-flow.md.REMOVED.git-id
@@ -0,0 +1 @@
+9e5e5f39071f0105c5fea3cdfe1bde6ced91e665
diff --git a/docs/tutorials/essentials/part-4-using-data.md.REMOVED.git-id b/docs/tutorials/essentials/part-4-using-data.md.REMOVED.git-id
@@ -0,0 +1 @@
+f9216d2a79b0c05ee2ebfecbdcf786c786b680ca
diff --git a/docs/tutorials/essentials/part-5-async-logic.md.REMOVED.git-id b/docs/tutorials/essentials/part-5-async-logic.md.REMOVED.git-id
@@ -0,0 +1 @@
+fd931e4cc77ef0873cf2616f67470c9dc34fb93c
diff --git a/docs/tutorials/essentials/part-6-performance-normalization.md.REMOVED.git-id b/docs/tutorials/essentials/part-6-performance-normalization.md.REMOVED.git-id
@@ -0,0 +1 @@
+e90eca8cefc46ad15cd427e86c450e8053756ac9
diff --git a/docs/tutorials/tutorials-index.md b/docs/tutorials/tutorials-index.md
@@ -0,0 +1,27 @@
+---
+id: tutorials-index
+slug: index
+title: 'Redux Tutorials Index'
+sidebar_label: 'Tutorials Index'
+hide_title: true
+description: 'Overview of the Redux tutorial pages'
+---
+
+# Redux Tutorials Index
+
+We have two different sets of tutorials:
+
+- The [**Redux Essentials tutorial**](./essentials/part-1-overview-concepts) is a "top-down" tutorial that teaches how to use Redux the right way, using our latest recommended APIs and best practices.
+- The [**Basic tutorial**](../basics/README.md) and [**Advanced tutorial**](../advanced/README.md) are a "bottom-up" tutorial that teaches how Redux works, starting from first principles.
+
+:::tip
+
+**We recommend starting with the [Redux Essentials tutorial](./essentials/part-1-overview-concepts)**, since it covers the key points you need to know about how to get started using Redux to write actual applications.
+
+:::
+
+:::info
+
+While the concepts in the "Basic" and "Advanced" tutorials are still valid, those pages are some of the oldest parts of our docs. We'll be updating those tutorials soon to improve the explanations and show some patterns that are simpler and easier to use. Keep an eye out for those updates. We'll also be reorganizing our docs to make it easier to find information.
+
+:::
diff --git a/netlify.toml b/netlify.toml
@@ -1,4 +1,4 @@
 [build]
   base    = "website"
   publish = "website/build"
-  command = "npm run build"
+  command = "npm run build && cp _redirects ./build"
diff --git a/website/_redirects.REMOVED.git-id b/website/_redirects.REMOVED.git-id
@@ -1 +1 @@
-264d61e663e772ec5e15704bcb7223de2694e923
+52175f9b303200d7f9a2942b11f405b53a3570d5
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -24,6 +24,11 @@ module.exports = {
           to: 'introduction/getting-started',
           position: 'right'
         },
+        {
+          label: 'Tutorial',
+          to: 'tutorials/essentials/part-1-overview-concepts',
+          position: 'right'
+        },
         { label: 'API', to: 'api/api-reference', position: 'right' },
         { label: 'FAQ', to: 'faq', position: 'right' },
         {
@@ -48,6 +53,10 @@ module.exports = {
               label: 'Getting Started',
               to: 'introduction/getting-started'
             },
+            {
+              label: 'Tutorial',
+              to: 'tutorials/essentials/part-1-overview-concepts'
+            },
             {
               label: 'FAQ',
               to: 'faq'
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -11,23 +11,46 @@ module.exports = {
       'introduction/ecosystem',
       'introduction/examples'
     ],
-    'Basic Tutorial': [
-      'basics/basic-tutorial',
-      'basics/actions',
-      'basics/reducers',
-      'basics/store',
-      'basics/data-flow',
-      'basics/usage-with-react',
-      'basics/example'
-    ],
-    'Advanced Tutorial': [
-      'advanced/advanced-tutorial',
-      'advanced/async-actions',
-      'advanced/async-flow',
-      'advanced/middleware',
-      'advanced/usage-with-react-router',
-      'advanced/example-reddit-api',
-      'advanced/next-steps'
+    Tutorials: [
+      'tutorials/tutorials-index',
+      {
+        type: 'category',
+        label: 'Redux Essentials',
+        items: [
+          'tutorials/essentials/part-1-overview-concepts',
+          'tutorials/essentials/part-2-app-structure',
+          'tutorials/essentials/part-3-data-flow',
+          'tutorials/essentials/part-4-using-data',
+          'tutorials/essentials/part-5-async-logic',
+          'tutorials/essentials/part-6-performance-normalization'
+        ]
+      },
+      {
+        type: 'category',
+        label: 'Basic Tutorial',
+        items: [
+          'basics/basic-tutorial',
+          'basics/actions',
+          'basics/reducers',
+          'basics/store',
+          'basics/data-flow',
+          'basics/usage-with-react',
+          'basics/example'
+        ]
+      },
+      {
+        type: 'category',
+        label: 'Advanced Tutorial',
+        items: [
+          'advanced/advanced-tutorial',
+          'advanced/async-actions',
+          'advanced/async-flow',
+          'advanced/middleware',
+          'advanced/usage-with-react-router',
+          'advanced/example-reddit-api',
+          'advanced/next-steps'
+        ]
+      }
     ],
     Recipes: [
       'recipes/recipe-index',
diff --git a/website/src/css/custom.css b/website/src/css/custom.css
diff --git a/website/src/css/custom.css.REMOVED.git-id b/website/src/css/custom.css.REMOVED.git-id
@@ -0,0 +1 @@
+52d1a5e8aa62637c2360b892ad7ac37595ad73a6
diff --git a/website/static/img/tutorials/essentials/ReduxDataFlowDiagram.gif.REMOVED.git-id b/website/static/img/tutorials/essentials/ReduxDataFlowDiagram.gif.REMOVED.git-id
@@ -0,0 +1 @@
+1960d04496daa72c9cfe37315fdeaed5f80e72b0
diff --git a/website/static/img/tutorials/essentials/devtools-done-clicking.png.REMOVED.git-id b/website/static/img/tutorials/essentials/devtools-done-clicking.png.REMOVED.git-id
@@ -0,0 +1 @@
+5e5d405f709b53ba0e105e8cf91b310c1b2bd0c1
diff --git a/website/static/img/tutorials/essentials/devtools-first-action.png.REMOVED.git-id b/website/static/img/tutorials/essentials/devtools-first-action.png.REMOVED.git-id
@@ -0,0 +1 @@
+7be869667b0198178501aaeeb936a70512c63800
diff --git a/website/static/img/tutorials/essentials/devtools-initial.png.REMOVED.git-id b/website/static/img/tutorials/essentials/devtools-initial.png.REMOVED.git-id
@@ -0,0 +1 @@
+088138480a88c76ec45b2fb85550633019aae409
diff --git a/website/static/img/tutorials/essentials/devtools-posts-fulfilled.png.REMOVED.git-id b/website/static/img/tutorials/essentials/devtools-posts-fulfilled.png.REMOVED.git-id
@@ -0,0 +1 @@
+e75c221535eeb86f9c1cca9f03f7ad24c788729c
diff --git a/website/static/img/tutorials/essentials/devtools-posts-pending.png.REMOVED.git-id b/website/static/img/tutorials/essentials/devtools-posts-pending.png.REMOVED.git-id
@@ -0,0 +1 @@
+bc331533459bee46bc45af55cd1d6fad1b408908
diff --git a/website/static/img/tutorials/essentials/example-initial-posts-list.png.REMOVED.git-id b/website/static/img/tutorials/essentials/example-initial-posts-list.png.REMOVED.git-id
@@ -0,0 +1 @@
+677efdff0fb008dcefc79742bf056782c30a7c07
diff --git a/website/static/img/tutorials/essentials/example-initial-posts.png.REMOVED.git-id b/website/static/img/tutorials/essentials/example-initial-posts.png.REMOVED.git-id
@@ -0,0 +1 @@
+72ca72046a0136575d3293117965893773302078
diff --git a/website/static/img/tutorials/essentials/example-postAdded-action.png.REMOVED.git-id b/website/static/img/tutorials/essentials/example-postAdded-action.png.REMOVED.git-id
@@ -0,0 +1 @@
+124d54cff880f8042d64187eacf549a1e4227925
diff --git a/website/static/img/tutorials/essentials/notifications-initial.png.REMOVED.git-id b/website/static/img/tutorials/essentials/notifications-initial.png.REMOVED.git-id
@@ -0,0 +1 @@
+965bdb26a864418447ca854bfb59918568b99ba0
diff --git a/website/static/img/tutorials/essentials/notifications-new.png.REMOVED.git-id b/website/static/img/tutorials/essentials/notifications-new.png.REMOVED.git-id
@@ -0,0 +1 @@
+376e2e6f54c7337b09b2f07370b785730d288d13
diff --git a/website/static/img/tutorials/essentials/one-way-data-flow.png.REMOVED.git-id b/website/static/img/tutorials/essentials/one-way-data-flow.png.REMOVED.git-id
@@ -0,0 +1 @@
+8a18b59cfef504c0549154a17f369cb3e3671b38
diff --git a/website/static/img/tutorials/essentials/posts-unknownAuthor.png.REMOVED.git-id b/website/static/img/tutorials/essentials/posts-unknownAuthor.png.REMOVED.git-id
@@ -0,0 +1 @@
+d4701ae8ccf910a89c8b334203fe01dc7f907477
diff --git a/website/static/img/tutorials/essentials/postslist-optimized.png.REMOVED.git-id b/website/static/img/tutorials/essentials/postslist-optimized.png.REMOVED.git-id
@@ -0,0 +1 @@
+6427298f4dedc840d46ca9dd801c0f5f44539cbc
diff --git a/website/static/img/tutorials/essentials/postslist-rerender.png.REMOVED.git-id b/website/static/img/tutorials/essentials/postslist-rerender.png.REMOVED.git-id
@@ -0,0 +1 @@
+973d54c8b9ea648bf2914620eb88d66eced0095f
diff --git a/website/static/img/tutorials/essentials/userpage-rerender.png.REMOVED.git-id b/website/static/img/tutorials/essentials/userpage-rerender.png.REMOVED.git-id

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-c6206af164afffc7f7cc75f060a2329fcb8d213c`
	`1`	`+06c2c8fd1f8d1d3e11232d26f91223eccec1d8f3`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-c1009f22843241280a4c6e9a9064536491e11266`
	`1`	`+73670ac005460e36ca5978f3a82499a22bffc84a`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-a0c4ec513de343fe7c98730e3b0fdd21b4b088ef`
	`1`	`+d626d6f8aad44259d58ad4e5ade603beaa539c1d`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+a4df5f1f297652579e324e960d423e8e9faccb7d`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+4ad20f607ad7d35a63efbfa3bf75682b9f12f83a`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+9e5e5f39071f0105c5fea3cdfe1bde6ced91e665`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+f9216d2a79b0c05ee2ebfecbdcf786c786b680ca`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+fd931e4cc77ef0873cf2616f67470c9dc34fb93c`