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 {
|
export interface DocusaurusConfig {
|
||||||
baseUrl: string;
|
baseUrl: string;
|
||||||
|
baseUrlIssueBanner: boolean;
|
||||||
favicon: string;
|
favicon: string;
|
||||||
tagline?: string;
|
tagline?: string;
|
||||||
title: string;
|
title: string;
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,7 @@ import siteMetadata from '@generated/site-metadata';
|
||||||
import renderRoutes from './exports/renderRoutes';
|
import renderRoutes from './exports/renderRoutes';
|
||||||
import DocusaurusContext from './exports/context';
|
import DocusaurusContext from './exports/context';
|
||||||
import PendingNavigation from './PendingNavigation';
|
import PendingNavigation from './PendingNavigation';
|
||||||
import BaseUrlSuggestionWarning from './baseUrlSuggestionWarning/BaseUrlSuggestionWarning';
|
import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
|
||||||
|
|
||||||
import './client-lifecycles-dispatcher';
|
import './client-lifecycles-dispatcher';
|
||||||
|
|
||||||
|
|
@ -28,7 +28,7 @@ function App(): JSX.Element {
|
||||||
return (
|
return (
|
||||||
<DocusaurusContext.Provider
|
<DocusaurusContext.Provider
|
||||||
value={{siteConfig, siteMetadata, globalData, isClient}}>
|
value={{siteConfig, siteMetadata, globalData, isClient}}>
|
||||||
<BaseUrlSuggestionWarning />
|
<BaseUrlIssueBanner />
|
||||||
<PendingNavigation routes={routes}>
|
<PendingNavigation routes={routes}>
|
||||||
{renderRoutes(routes)}
|
{renderRoutes(routes)}
|
||||||
</PendingNavigation>
|
</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`] = `
|
exports[`loadConfig website with valid siteConfig 1`] = `
|
||||||
Object {
|
Object {
|
||||||
"baseUrl": "/",
|
"baseUrl": "/",
|
||||||
|
"baseUrlIssueBanner": true,
|
||||||
"customFields": Object {},
|
"customFields": Object {},
|
||||||
"favicon": "img/docusaurus.ico",
|
"favicon": "img/docusaurus.ico",
|
||||||
"noIndex": false,
|
"noIndex": false,
|
||||||
|
|
|
||||||
|
|
@ -26,6 +26,7 @@ export const DEFAULT_CONFIG: Pick<
|
||||||
| 'themeConfig'
|
| 'themeConfig'
|
||||||
| 'titleDelimiter'
|
| 'titleDelimiter'
|
||||||
| 'noIndex'
|
| 'noIndex'
|
||||||
|
| 'baseUrlIssueBanner'
|
||||||
> = {
|
> = {
|
||||||
onBrokenLinks: 'throw',
|
onBrokenLinks: 'throw',
|
||||||
onBrokenMarkdownLinks: 'warn',
|
onBrokenMarkdownLinks: 'warn',
|
||||||
|
|
@ -37,6 +38,7 @@ export const DEFAULT_CONFIG: Pick<
|
||||||
themeConfig: {},
|
themeConfig: {},
|
||||||
titleDelimiter: '|',
|
titleDelimiter: '|',
|
||||||
noIndex: false,
|
noIndex: false,
|
||||||
|
baseUrlIssueBanner: true,
|
||||||
};
|
};
|
||||||
|
|
||||||
const PluginSchema = Joi.alternatives().try(
|
const PluginSchema = Joi.alternatives().try(
|
||||||
|
|
@ -61,6 +63,7 @@ const ConfigSchema = Joi.object({
|
||||||
.required()
|
.required()
|
||||||
.regex(new RegExp('/$', 'm'))
|
.regex(new RegExp('/$', 'm'))
|
||||||
.message('{{#label}} must be a string with a trailing `/`'),
|
.message('{{#label}} must be a string with a trailing `/`'),
|
||||||
|
baseUrlIssueBanner: Joi.boolean().default(DEFAULT_CONFIG.baseUrlIssueBanner),
|
||||||
favicon: Joi.string().required(),
|
favicon: Joi.string().required(),
|
||||||
title: Joi.string().required(),
|
title: Joi.string().required(),
|
||||||
url: URISchema.required(),
|
url: URISchema.required(),
|
||||||
|
|
|
||||||
|
|
@ -424,3 +424,27 @@ module.exports = {
|
||||||
titleDelimiter: '🦖', // Defaults to `|`
|
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',
|
organizationName: 'facebook',
|
||||||
projectName: 'docusaurus',
|
projectName: 'docusaurus',
|
||||||
baseUrl,
|
baseUrl,
|
||||||
|
baseUrlIssueBanner: true,
|
||||||
url: 'https://v2.docusaurus.io',
|
url: 'https://v2.docusaurus.io',
|
||||||
onBrokenLinks: isVersioningDisabled ? 'warn' : 'throw',
|
onBrokenLinks: isVersioningDisabled ? 'warn' : 'throw',
|
||||||
onBrokenMarkdownLinks: 'warn',
|
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