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, }}> - - - {renderRoutes(routes)} - + + + + {renderRoutes(routes)} + + ); } 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; 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 `` + +A `` 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 ``, and will **never unmount**. + +:::tip + +Use this component render React Context providers and global stateful logic. + +::: ## Swizzling theme components