mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 15:47:23 +02:00
feat(v2): add baseUrlIssueBanner configuration to disable banner (#3802)
* add baseUrlIssueBanner configuration * handle review
This commit is contained in:
Sébastien Lorber
GitHub
parent
9e314bcb11
commit
746a19f25b
11 changed files with 140 additions and 96 deletions
1
packages/docusaurus-types/src/index.d.ts
vendored
1
packages/docusaurus-types/src/index.d.ts
vendored
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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 (
|
||||
<DocusaurusContext.Provider
|
||||
value={{siteConfig, siteMetadata, globalData, isClient}}>
|
||||
<BaseUrlSuggestionWarning />
|
||||
<BaseUrlIssueBanner />
|
||||
<PendingNavigation routes={routes}>
|
||||
{renderRoutes(routes)}
|
||||
</PendingNavigation>
|
||||
|
|
|
|||
|
|
@ -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 (
|
||||
<>
|
||||
<Head>
|
||||
<script>
|
||||
{`
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
var baseUrlSuggestion = document.getElementById(
|
||||
'${BaseUrlIssueBannerContainerId}',
|
||||
);
|
||||
if (baseUrlSuggestion) {
|
||||
var actualHomePagePath = window.location.pathname;
|
||||
var suggestedBaseUrl = actualHomePagePath.substr(-1) === '/'
|
||||
? actualHomePagePath
|
||||
: actualHomePagePath + '/';
|
||||
baseUrlSuggestion.innerHTML = suggestedBaseUrl;
|
||||
}
|
||||
});
|
||||
`}
|
||||
</script>
|
||||
</Head>
|
||||
<div
|
||||
className={styles.baseUrlIssueBanner}
|
||||
style={{
|
||||
border: 'solid red thick',
|
||||
backgroundColor: '#ffe6b3',
|
||||
margin: 20,
|
||||
padding: 20,
|
||||
fontSize: 20,
|
||||
}}>
|
||||
<p
|
||||
style={{
|
||||
fontWeight: 'bold',
|
||||
fontSize: 30,
|
||||
}}>
|
||||
Your Docusaurus site did not load properly.
|
||||
</p>
|
||||
<p>
|
||||
A very common reason is a wrong site{' '}
|
||||
<a
|
||||
href="https://v2.docusaurus.io/docs/docusaurus.config.js/#baseurl"
|
||||
style={{fontWeight: 'bold'}}>
|
||||
baseUrl configuration
|
||||
</a>
|
||||
.
|
||||
</p>
|
||||
<p>
|
||||
Current configured baseUrl ={' '}
|
||||
<span style={{fontWeight: 'bold', color: 'red'}}>{baseUrl}</span>{' '}
|
||||
{baseUrl === '/' ? ' (default value)' : ''}
|
||||
</p>
|
||||
<p>
|
||||
We suggest trying baseUrl ={' '}
|
||||
<span
|
||||
style={{fontWeight: 'bold', color: 'green'}}
|
||||
id={BaseUrlIssueBannerContainerId}
|
||||
/>{' '}
|
||||
</p>
|
||||
</div>
|
||||
</>
|
||||
);
|
||||
}
|
||||
|
|
@ -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;
|
||||
}
|
||||
|
|
@ -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 (
|
||||
<>
|
||||
<Head>
|
||||
<script type="text/javascript">
|
||||
{`
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
var baseUrlSuggestion = document.getElementById(
|
||||
'${BaseUrlSuggestionContainerId}',
|
||||
);
|
||||
if (baseUrlSuggestion) {
|
||||
var actualHomePagePath = window.location.pathname;
|
||||
var suggestedBaseUrl = actualHomePagePath.substr(-1) === '/'
|
||||
? actualHomePagePath
|
||||
: actualHomePagePath + '/';
|
||||
baseUrlSuggestion.innerHTML = suggestedBaseUrl;
|
||||
}
|
||||
});
|
||||
`}
|
||||
</script>
|
||||
</Head>
|
||||
<div
|
||||
className={styles.baseUrlSuggestionWarning}
|
||||
style={{
|
||||
border: 'solid red thick',
|
||||
backgroundColor: '#ffe6b3',
|
||||
margin: 20,
|
||||
padding: 20,
|
||||
fontSize: 20,
|
||||
}}>
|
||||
<p
|
||||
style={{
|
||||
fontWeight: 'bold',
|
||||
fontSize: 30,
|
||||
}}>
|
||||
Your Docusaurus site did not load properly.
|
||||
</p>
|
||||
<p>
|
||||
A very common reason is a wrong site{' '}
|
||||
<a
|
||||
href="https://v2.docusaurus.io/docs/docusaurus.config.js/#baseurl"
|
||||
style={{fontWeight: 'bold'}}>
|
||||
baseUrl configuration
|
||||
</a>
|
||||
.
|
||||
</p>
|
||||
<p>
|
||||
Current configured baseUrl ={' '}
|
||||
<span style={{fontWeight: 'bold', color: 'red'}}>{baseUrl}</span>{' '}
|
||||
{baseUrl === '/' ? ' (default value)' : ''}
|
||||
</p>
|
||||
<p>
|
||||
We suggest trying baseUrl ={' '}
|
||||
<span
|
||||
style={{fontWeight: 'bold', color: 'green'}}
|
||||
id={BaseUrlSuggestionContainerId}
|
||||
/>{' '}
|
||||
</p>
|
||||
</div>
|
||||
</>
|
||||
);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
.baseUrlSuggestionWarning {
|
||||
display: none;
|
||||
}
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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(),
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
:::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.
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -47,6 +47,7 @@ module.exports = {
|
|||
organizationName: 'facebook',
|
||||
projectName: 'docusaurus',
|
||||
baseUrl,
|
||||
baseUrlIssueBanner: true,
|
||||
url: 'https://v2.docusaurus.io',
|
||||
onBrokenLinks: isVersioningDisabled ? 'warn' : 'throw',
|
||||
onBrokenMarkdownLinks: 'warn',
|
||||
|
|
|
|||
BIN
website/static/img/baseUrlIssueBanner.png
Normal file
BIN
website/static/img/baseUrlIssueBanner.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 268 KiB |
Loading…
Add table
Add a link
Reference in a new issue