From dc92edaf99bba3e432a7f3909e36ad0e4ec22fbc Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Thu, 17 Dec 2020 18:52:48 +0100
Subject: [PATCH 1/2] Add <Root> component

---
 packages/docusaurus/src/client/App.tsx        | 11 ++++++----
 .../src/client/theme-fallback/Root/index.js   | 21 +++++++++++++++++++
 2 files changed, 28 insertions(+), 4 deletions(-)
 create mode 100644 packages/docusaurus/src/client/theme-fallback/Root/index.js

diff --git a/packages/docusaurus/src/client/App.tsx b/packages/docusaurus/src/client/App.tsx
index 5a22629ab03a..e14808538bd1 100644
--- a/packages/docusaurus/src/client/App.tsx
+++ b/packages/docusaurus/src/client/App.tsx
@@ -17,6 +17,7 @@ import renderRoutes from './exports/renderRoutes';
 import DocusaurusContext from './exports/context';
 import PendingNavigation from './PendingNavigation';
 import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
+import Root from '@theme/Root';
 
 import './client-lifecycles-dispatcher';
 
@@ -37,10 +38,12 @@ function App(): JSX.Element {
         codeTranslations,
         isClient,
       }}>
-      <BaseUrlIssueBanner />
-      <PendingNavigation routes={routes}>
-        {renderRoutes(routes)}
-      </PendingNavigation>
+      <Root>
+        <BaseUrlIssueBanner />
+        <PendingNavigation routes={routes}>
+          {renderRoutes(routes)}
+        </PendingNavigation>
+      </Root>
     </DocusaurusContext.Provider>
   );
 }
diff --git a/packages/docusaurus/src/client/theme-fallback/Root/index.js b/packages/docusaurus/src/client/theme-fallback/Root/index.js
new file mode 100644
index 000000000000..2e9476d4edba
--- /dev/null
+++ b/packages/docusaurus/src/client/theme-fallback/Root/index.js
@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+// Wrapper at the very top of the app, that is applied constantly
+// and does not depend on current route (unlike the layout)
+//
+// Gives the opportunity to add stateful providers on top of the app
+// and these providers won't reset state when we navigate
+//
+// See https://github.com/facebook/docusaurus/issues/3919
+function Root({children}) {
+  return <>{children}</>;
+}
+
+export default Root;

From 2f0914bfab3f83b5be694c9b828ab78a0adc81c9 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Thu, 17 Dec 2020 19:22:23 +0100
Subject: [PATCH 2/2] add some <Root> doc

---
 website/docs/using-themes.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md
index 1ef3d0dc0e4e..693e1fbde807 100644
--- a/website/docs/using-themes.md
+++ b/website/docs/using-themes.md
@@ -71,7 +71,30 @@ And if you want to use Bootstrap styling, you can swap out the theme with `theme
 }
 ```
 
-The content plugin remains the same and the only thing you need to change is the theme.
+## Wrapper your site with `<Root>`
+
+A `<Root>` theme component is rendered at the very top of your Docusaurus site.
+
+It allows you to wrap your site with additional logic, by creating a file at `website/src/theme/Root.js`:
+
+```js title="website/src/theme/Root.js"
+import React from 'react';
+
+// Default implementation, that you can customize
+function Root({children}) {
+  return <>{children}</>;
+}
+
+export default Root;
+```
+
+This component is applied above the router and the theme `<Layout>`, and will **never unmount**.
+
+:::tip
+
+Use this component render React Context providers and global stateful logic.
+
+:::
 
 ## Swizzling theme components