diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts index af651ad8ec83..42a3d73ffde3 100644 --- a/packages/docusaurus-types/src/index.d.ts +++ b/packages/docusaurus-types/src/index.d.ts @@ -16,6 +16,7 @@ export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'error' | 'throw'; export interface DocusaurusConfig { baseUrl: string; + baseUrlIssueBanner: boolean; favicon: string; tagline?: string; title: string; diff --git a/packages/docusaurus/src/client/App.tsx b/packages/docusaurus/src/client/App.tsx index 85e4858b18ca..f30d37a7c24a 100644 --- a/packages/docusaurus/src/client/App.tsx +++ b/packages/docusaurus/src/client/App.tsx @@ -14,7 +14,7 @@ import siteMetadata from '@generated/site-metadata'; import renderRoutes from './exports/renderRoutes'; import DocusaurusContext from './exports/context'; import PendingNavigation from './PendingNavigation'; -import BaseUrlSuggestionWarning from './baseUrlSuggestionWarning/BaseUrlSuggestionWarning'; +import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner'; import './client-lifecycles-dispatcher'; @@ -28,7 +28,7 @@ function App(): JSX.Element { return ( - + {renderRoutes(routes)} diff --git a/packages/docusaurus/src/client/baseUrlIssueBanner/BaseUrlIssueBanner.tsx b/packages/docusaurus/src/client/baseUrlIssueBanner/BaseUrlIssueBanner.tsx new file mode 100644 index 000000000000..25a59b644836 --- /dev/null +++ b/packages/docusaurus/src/client/baseUrlIssueBanner/BaseUrlIssueBanner.tsx @@ -0,0 +1,98 @@ +/** + * 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'; +import {useLocation} from 'react-router-dom'; + +import Head from '../exports/Head'; + +import styles from './styles.module.css'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +// We want to help the users with a bad baseUrl configuration (very common error) +// Help message is inlined, and hides if the external CSS is able to load successfully +// Note: it might create false positives (ie network failures): not a big deal +// Note: we only inline this for the homepage to avoid polluting all the site's pages +// See https://github.com/facebook/docusaurus/pull/3621 +export default function BaseUrlIssueBanner() { + const { + siteConfig: {baseUrl, baseUrlIssueBanner}, + } = useDocusaurusContext(); + const {pathname} = useLocation(); + + // returns true for the homepage during SRR + const isHomePage = pathname === baseUrl; + + const shouldRender = baseUrlIssueBanner && isHomePage; + + if (!shouldRender) { + return null; + } + + const BaseUrlIssueBannerContainerId = 'base-url-issue-banner-container'; + + return ( + <> + + + +
+

+ Your Docusaurus site did not load properly. +

+

+ A very common reason is a wrong site{' '} + + baseUrl configuration + + . +

+

+ Current configured baseUrl ={' '} + {baseUrl}{' '} + {baseUrl === '/' ? ' (default value)' : ''} +

+

+ We suggest trying baseUrl ={' '} + {' '} +

+
+ + ); +} diff --git a/packages/docusaurus/src/client/baseUrlIssueBanner/styles.module.css b/packages/docusaurus/src/client/baseUrlIssueBanner/styles.module.css new file mode 100644 index 000000000000..564e527948c5 --- /dev/null +++ b/packages/docusaurus/src/client/baseUrlIssueBanner/styles.module.css @@ -0,0 +1,10 @@ +/** + * 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. + */ + +.baseUrlIssueBanner { + display: none; +} diff --git a/packages/docusaurus/src/client/baseUrlSuggestionWarning/BaseUrlSuggestionWarning.tsx b/packages/docusaurus/src/client/baseUrlSuggestionWarning/BaseUrlSuggestionWarning.tsx deleted file mode 100644 index 7f2406d2b1cf..000000000000 --- a/packages/docusaurus/src/client/baseUrlSuggestionWarning/BaseUrlSuggestionWarning.tsx +++ /dev/null @@ -1,91 +0,0 @@ -/** - * 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'; -import {useLocation} from 'react-router-dom'; - -import siteConfig from '@generated/docusaurus.config'; -import Head from '../exports/Head'; - -import styles from './styles.module.css'; - -// We want to help the users with a bad baseUrl configuration (very common error) -// Help message is inlined, and hides if the external CSS is able to load successfully -// Note: it might create false positives (ie network failures): not a big deal -// Note: we only inline this for the homepage to avoid polluting all the site's pages -// See https://github.com/facebook/docusaurus/pull/3621 -export default function BaseUrlSuggestionWarning() { - const {baseUrl} = siteConfig; - const {pathname} = useLocation(); - const isHomePage = pathname === baseUrl; // returns true for the homepage during SRR - - const BaseUrlSuggestionContainerId = 'base-url-suggestion-container'; - - if (isHomePage) { - return ( - <> - - - -
-

- Your Docusaurus site did not load properly. -

-

- A very common reason is a wrong site{' '} - - baseUrl configuration - - . -

-

- Current configured baseUrl ={' '} - {baseUrl}{' '} - {baseUrl === '/' ? ' (default value)' : ''} -

-

- We suggest trying baseUrl ={' '} - {' '} -

-
- - ); - } - return null; -} diff --git a/packages/docusaurus/src/client/baseUrlSuggestionWarning/styles.module.css b/packages/docusaurus/src/client/baseUrlSuggestionWarning/styles.module.css deleted file mode 100644 index c3243ffb00fa..000000000000 --- a/packages/docusaurus/src/client/baseUrlSuggestionWarning/styles.module.css +++ /dev/null @@ -1,3 +0,0 @@ -.baseUrlSuggestionWarning { - display: none; -} diff --git a/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap b/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap index 9f4f77ad184c..3d2cc5e1e4b5 100644 --- a/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap +++ b/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap @@ -18,6 +18,7 @@ See https://v2.docusaurus.io/docs/docusaurus.config.js/#customfields" exports[`loadConfig website with valid siteConfig 1`] = ` Object { "baseUrl": "/", + "baseUrlIssueBanner": true, "customFields": Object {}, "favicon": "img/docusaurus.ico", "noIndex": false, diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts index 0e8700ac9f59..dc1ce1514b34 100644 --- a/packages/docusaurus/src/server/configValidation.ts +++ b/packages/docusaurus/src/server/configValidation.ts @@ -26,6 +26,7 @@ export const DEFAULT_CONFIG: Pick< | 'themeConfig' | 'titleDelimiter' | 'noIndex' + | 'baseUrlIssueBanner' > = { onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', @@ -37,6 +38,7 @@ export const DEFAULT_CONFIG: Pick< themeConfig: {}, titleDelimiter: '|', noIndex: false, + baseUrlIssueBanner: true, }; const PluginSchema = Joi.alternatives().try( @@ -61,6 +63,7 @@ const ConfigSchema = Joi.object({ .required() .regex(new RegExp('/$', 'm')) .message('{{#label}} must be a string with a trailing `/`'), + baseUrlIssueBanner: Joi.boolean().default(DEFAULT_CONFIG.baseUrlIssueBanner), favicon: Joi.string().required(), title: Joi.string().required(), url: URISchema.required(), diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md index df2d56dfca24..d5829bed584c 100644 --- a/website/docs/api/docusaurus.config.js.md +++ b/website/docs/api/docusaurus.config.js.md @@ -424,3 +424,27 @@ module.exports = { titleDelimiter: '🦖', // Defaults to `|` }; ``` + +### `baseUrlIssueBanner` + +- Type: `boolean` + +When enabled, will show a banner in case your site can't load its CSS or JavaScript files, which is a very common issue, often related to a wrong `baseUrl` in site config. + +Example: + +```js title="docusaurus.config.js" +module.exports = { + baseUrlIssueBanner: true, // Defaults to `true` +}; +``` + +![baseUrlIssueBanner](/img/baseUrlIssueBanner.png) + +:::caution + +This banner need to inline CSS / JS. + +If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), you should rather disable it. + +::: diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 80b10bd7f418..442cdfe24f3b 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -47,6 +47,7 @@ module.exports = { organizationName: 'facebook', projectName: 'docusaurus', baseUrl, + baseUrlIssueBanner: true, url: 'https://v2.docusaurus.io', onBrokenLinks: isVersioningDisabled ? 'warn' : 'throw', onBrokenMarkdownLinks: 'warn', diff --git a/website/static/img/baseUrlIssueBanner.png b/website/static/img/baseUrlIssueBanner.png new file mode 100644 index 000000000000..1a372e214493 Binary files /dev/null and b/website/static/img/baseUrlIssueBanner.png differ