mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-07 13:22:26 +02:00
feat(v2): officially release @docusaurus/plugin-debug (#3392)
* Add json styling to config debug
* Style debug content page
* Add style and collapse depth to json viewer
* Add style to debug layout
* Add style to metadata debug
* Add style support to registry debugger
* Remove default content if other instances are present
* Change colors for more contrast
* Add debug routes styles
* Add active link style
* Fix container css issues
* Style registry debug page
* Remove unused style modules
* Add white space to style files
* Add font scaling
* Fix prettier errors
* Add child routes to route debug
* Readd default content plugin json
* Add empty home page to debug
* Prettier
* Revert "Add empty home page to debug"
This should be included in a separate PR
This reverts commit 9c43c9f7fb.
* Set colors to dark theme
* Add plugin debug doc + minor fixes + expose global data
* more debug plugin doc
Co-authored-by: Drewbi <drewalexander986@gmail.com>
This commit is contained in:
Sébastien Lorber
GitHub
parent
8f24a0a149
commit
9857f7b2b5
19 changed files with 301 additions and 104 deletions
|
|
@ -50,7 +50,7 @@ export default function pluginContentPages({
|
|||
|
||||
addRoute({
|
||||
path: normalizeUrl([baseUrl, '__docusaurus/debug/metadata']),
|
||||
component: '@theme/DebugMetadata',
|
||||
component: '@theme/DebugSiteMetadata',
|
||||
exact: true,
|
||||
});
|
||||
|
||||
|
|
@ -74,6 +74,12 @@ export default function pluginContentPages({
|
|||
allContent: aliasedSource(allContentPath),
|
||||
},
|
||||
});
|
||||
|
||||
addRoute({
|
||||
path: normalizeUrl([baseUrl, '__docusaurus/debug/globalData']),
|
||||
component: '@theme/DebugGlobalData',
|
||||
exact: true,
|
||||
});
|
||||
},
|
||||
|
||||
configureWebpack() {
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@
|
|||
import React from 'react';
|
||||
|
||||
import DebugLayout from '../DebugLayout';
|
||||
import DebugJsonView from '../DebugJsonView';
|
||||
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
|
||||
function DebugMetadata() {
|
||||
|
|
@ -15,7 +17,7 @@ function DebugMetadata() {
|
|||
return (
|
||||
<DebugLayout>
|
||||
<h2>Site config</h2>
|
||||
<div>{JSON.stringify(siteConfig, null, 2)}</div>
|
||||
<DebugJsonView src={siteConfig} collapseDepth="3" />
|
||||
</DebugLayout>
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,7 +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.
|
||||
*/
|
||||
|
||||
|
|
@ -5,35 +5,22 @@
|
|||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
import React, {useState} from 'react';
|
||||
import React from 'react';
|
||||
|
||||
import DebugLayout from '../DebugLayout';
|
||||
import DebugJsonView from '../DebugJsonView';
|
||||
|
||||
const PluginInstanceContent = ({pluginId, pluginInstanceContent}) => (
|
||||
<section style={{marginBottom: 30}}>
|
||||
<h4>{`>> ${pluginId}`}</h4>
|
||||
<div
|
||||
style={{
|
||||
marginTop: 10,
|
||||
padding: 10,
|
||||
border: 'thin cyan solid',
|
||||
borderRadius: 5,
|
||||
backgroundColor: 'lightgrey',
|
||||
}}>
|
||||
<DebugJsonView src={pluginInstanceContent} />
|
||||
</div>
|
||||
<code>{pluginId}</code>
|
||||
<DebugJsonView src={pluginInstanceContent} collapseDepth="2" />
|
||||
</section>
|
||||
);
|
||||
|
||||
const PluginContent = ({pluginName, pluginContent}) => {
|
||||
const [visible, setVisible] = useState(true);
|
||||
return (
|
||||
<section style={{marginBottom: 60}}>
|
||||
<h3 onClick={() => setVisible((v) => !v)} style={{cursor: 'pointer'}}>
|
||||
{pluginName}
|
||||
</h3>
|
||||
{visible && (
|
||||
<h3>{pluginName}</h3>
|
||||
<div>
|
||||
{Object.entries(pluginContent)
|
||||
// filter plugin instances with no content
|
||||
|
|
@ -50,7 +37,6 @@ const PluginContent = ({pluginName, pluginContent}) => {
|
|||
);
|
||||
})}
|
||||
</div>
|
||||
)}
|
||||
</section>
|
||||
);
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,7 +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.
|
||||
*/
|
||||
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
/**
|
||||
* 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 DebugLayout from '../DebugLayout';
|
||||
import DebugJsonView from '../DebugJsonView';
|
||||
import useGlobalData from '@docusaurus/useGlobalData';
|
||||
|
||||
function DebugMetadata() {
|
||||
const globalData = useGlobalData();
|
||||
return (
|
||||
<DebugLayout>
|
||||
<h2>Global data</h2>
|
||||
<DebugJsonView src={globalData} collapseDepth="3" />
|
||||
</DebugLayout>
|
||||
);
|
||||
}
|
||||
|
||||
export default DebugMetadata;
|
||||
|
|
@ -25,17 +25,28 @@ const BrowserOnlyReactJson = (props) => {
|
|||
);
|
||||
};
|
||||
|
||||
function DebugJsonView({src}) {
|
||||
function DebugJsonView({src, collapseDepth}) {
|
||||
return (
|
||||
<BrowserOnlyReactJson
|
||||
src={src}
|
||||
style={{
|
||||
marginTop: '10px',
|
||||
padding: '10px',
|
||||
borderRadius: '4px',
|
||||
backgroundColor: '#292a2b',
|
||||
}}
|
||||
name={RootName}
|
||||
theme="paraiso"
|
||||
shouldCollapse={(field) => {
|
||||
// By default, we collapse the json for performance reasons
|
||||
// See https://github.com/mac-s-g/react-json-view/issues/235
|
||||
// only the "root" is not collapsed
|
||||
return field.name !== RootName;
|
||||
// Non-root elements that are larger than 50 fields are collapsed
|
||||
return field.name !== RootName && Object.keys(field.src).length > 50;
|
||||
}}
|
||||
collapsed={collapseDepth}
|
||||
groupArraysAfterLength="5"
|
||||
enableClipboard={false}
|
||||
displayDataTypes={false}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,7 +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.
|
||||
*/
|
||||
|
||||
|
|
@ -7,16 +7,17 @@
|
|||
|
||||
import React from 'react';
|
||||
import Link from '@docusaurus/Link';
|
||||
// import styles from './styles.module.css';
|
||||
import styles from './styles.module.css';
|
||||
|
||||
const DebugNavLink = ({to, children}) => (
|
||||
<Link
|
||||
style={{margin: 10}}
|
||||
className="button button--primary"
|
||||
className={styles.navlink}
|
||||
isNavLink
|
||||
activeClassName="button--active"
|
||||
to={to}
|
||||
exact>
|
||||
exact
|
||||
activeStyle={{
|
||||
backgroundColor: '#363739',
|
||||
}}>
|
||||
{children}
|
||||
</Link>
|
||||
);
|
||||
|
|
@ -24,14 +25,17 @@ const DebugNavLink = ({to, children}) => (
|
|||
function DebugLayout({children}) {
|
||||
return (
|
||||
<div>
|
||||
<nav style={{width: '100%', padding: 10, border: 'solid'}}>
|
||||
<nav className={styles.nav}>
|
||||
<DebugNavLink to="/__docusaurus/debug">Config</DebugNavLink>
|
||||
<DebugNavLink to="/__docusaurus/debug/metadata">Metadata</DebugNavLink>
|
||||
<DebugNavLink to="/__docusaurus/debug/registry">Registry</DebugNavLink>
|
||||
<DebugNavLink to="/__docusaurus/debug/routes">Routes</DebugNavLink>
|
||||
<DebugNavLink to="/__docusaurus/debug/content">Content</DebugNavLink>
|
||||
<DebugNavLink to="/__docusaurus/debug/globalData">
|
||||
Global data
|
||||
</DebugNavLink>
|
||||
</nav>
|
||||
<main style={{padding: 20}}>{children}</main>
|
||||
<main className={styles.container}>{children}</main>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,3 +4,72 @@
|
|||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
.container {
|
||||
padding: 20px;
|
||||
padding-top: 80px;
|
||||
overflow-x: hidden;
|
||||
background-color: #18191a;
|
||||
color: white;
|
||||
min-height: 100vh;
|
||||
}
|
||||
|
||||
.nav {
|
||||
position: fixed;
|
||||
display: flex;
|
||||
justify-content: space-evenly;
|
||||
align-items: center;
|
||||
height: 3.75rem;
|
||||
background-color: #242526;
|
||||
width: 100%;
|
||||
z-index: 1;
|
||||
}
|
||||
|
||||
.navlink {
|
||||
color: white;
|
||||
font-weight: 500;
|
||||
font-size: clamp(12px, 4vw, 16px);
|
||||
text-align: center;
|
||||
border-radius: 4px;
|
||||
padding: 6px 6px;
|
||||
}
|
||||
|
||||
.navlink:hover {
|
||||
text-decoration: none;
|
||||
background-color: #292a2b;
|
||||
}
|
||||
|
||||
code {
|
||||
color: white;
|
||||
background-color: #444950;
|
||||
}
|
||||
|
||||
.active {
|
||||
background-color: #363739;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 800px) {
|
||||
.nav {
|
||||
flex-direction: column;
|
||||
justify-content: flex-start;
|
||||
align-items: center;
|
||||
height: 100vh;
|
||||
width: 200px;
|
||||
float: left;
|
||||
background-color: #18191a;
|
||||
border-right: 1px solid #606770;
|
||||
padding-top: 20px;
|
||||
}
|
||||
|
||||
.navlink {
|
||||
width: 80%;
|
||||
margin-top: 20px;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.container {
|
||||
padding-top: 40px;
|
||||
float: right;
|
||||
width: calc(100% - 200px);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,7 +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.
|
||||
*/
|
||||
|
||||
|
|
@ -9,17 +9,21 @@ import React from 'react';
|
|||
|
||||
import DebugLayout from '../DebugLayout';
|
||||
import registry from '@generated/registry';
|
||||
import styles from './styles.module.css';
|
||||
|
||||
function DebugRegistry() {
|
||||
return (
|
||||
<DebugLayout>
|
||||
{' '}
|
||||
<h2>Registry</h2>
|
||||
<ul>
|
||||
<ul className={styles.list}>
|
||||
{Object.values(registry).map(([, aliasedPath, resolved]) => (
|
||||
<li key={aliasedPath}>
|
||||
<div>Aliased Path: {aliasedPath}</div>
|
||||
<div>Resolved Path: {resolved}</div>
|
||||
<li key={aliasedPath} className={styles.listItem}>
|
||||
<div style={{marginBottom: '10px'}}>
|
||||
Aliased Path: <code>{aliasedPath}</code>
|
||||
</div>
|
||||
<div>
|
||||
Resolved Path: <code>{resolved}</code>
|
||||
</div>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
|
|
|
|||
|
|
@ -5,3 +5,14 @@
|
|||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
.list {
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.listItem {
|
||||
list-style: none;
|
||||
background-color: #242526;
|
||||
padding: 10px;
|
||||
border-radius: 4px;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -8,17 +8,29 @@
|
|||
import React from 'react';
|
||||
|
||||
import DebugLayout from '../DebugLayout';
|
||||
import DebugJsonView from '../DebugJsonView';
|
||||
import routes from '@generated/routes';
|
||||
import styles from './styles.module.css';
|
||||
|
||||
function DebugRoutes() {
|
||||
return (
|
||||
<DebugLayout>
|
||||
<h2>Routes</h2>
|
||||
<ul>
|
||||
{routes.map(({path, exact}) => (
|
||||
<li key={path}>
|
||||
<div>Route: {path}</div>
|
||||
<div>Is exact: {String(Boolean(exact))}</div>
|
||||
<ul className={styles.list}>
|
||||
{routes.map(({path, exact, routes: childRoutes}) => (
|
||||
<li key={path} className={styles.listItem}>
|
||||
<div className={styles.route}>
|
||||
<code className={styles.routeName}>{path}</code>
|
||||
</div>
|
||||
<div>
|
||||
Is exact: <code>{String(Boolean(exact))}</code>
|
||||
</div>
|
||||
{childRoutes && (
|
||||
<div>
|
||||
Child Routes:
|
||||
<DebugJsonView src={childRoutes} />
|
||||
</div>
|
||||
)}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
|
|
|
|||
|
|
@ -5,3 +5,22 @@
|
|||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
.list {
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.listItem {
|
||||
list-style: none;
|
||||
background-color: #242526;
|
||||
padding: 10px;
|
||||
border-radius: 4px;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
|
||||
.route {
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
.routeName {
|
||||
color: #e06b6b;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -9,26 +9,32 @@ import React from 'react';
|
|||
|
||||
import DebugLayout from '../DebugLayout';
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
import styles from './styles.module.css';
|
||||
|
||||
function DebugMetadata() {
|
||||
const {siteMetadata} = useDocusaurusContext();
|
||||
return (
|
||||
<DebugLayout>
|
||||
<h2>Site Metadata</h2>
|
||||
<div>Docusaurus Version: {siteMetadata.docusaurusVersion}</div>
|
||||
<div>
|
||||
Site Version: {siteMetadata.siteVersion || 'No version specified'}
|
||||
Docusaurus Version: <code>{siteMetadata.docusaurusVersion}</code>
|
||||
</div>
|
||||
<h3>Plugins and themes:</h3>
|
||||
<ul>
|
||||
<div>
|
||||
Site Version:{' '}
|
||||
<code>{siteMetadata.siteVersion || 'No version specified'}</code>
|
||||
</div>
|
||||
<h3 className={styles.sectionTitle}>Plugins and themes</h3>
|
||||
<ul className={styles.list}>
|
||||
{Object.entries(siteMetadata.pluginVersions).map(
|
||||
([name, versionInformation]) => (
|
||||
<li key={name}>
|
||||
<div>Name: {name}</div>
|
||||
<div>Type: {versionInformation.type}</div>
|
||||
<li key={name} className={styles.listItem}>
|
||||
{versionInformation.version && (
|
||||
<div>Version: {versionInformation.version}</div>
|
||||
<div className={styles.version}>
|
||||
<code>{versionInformation.version}</code>
|
||||
</div>
|
||||
)}
|
||||
<div className={styles.name}>{name}</div>
|
||||
<div>Type: {versionInformation.type}</div>
|
||||
</li>
|
||||
),
|
||||
)}
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
/**
|
||||
* 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.
|
||||
*/
|
||||
|
||||
.sectionTitle {
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.list {
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.listItem {
|
||||
list-style: none;
|
||||
background-color: #242526;
|
||||
padding: 10px;
|
||||
border-radius: 4px;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
|
||||
.version {
|
||||
float: right;
|
||||
}
|
||||
|
||||
.name {
|
||||
font-weight: 800;
|
||||
color: #e06b6b;
|
||||
}
|
||||
|
|
@ -80,6 +80,7 @@ The classic preset that is usually shipped by default to new docusaurus website.
|
|||
| `@docusaurus/theme-classic` | `@docusaurus/plugin-content-docs` |
|
||||
| `@docusaurus/theme-search-algolia` | `@docusaurus/plugin-content-blog` |
|
||||
| | `@docusaurus/plugin-content-pages` |
|
||||
| | `@docusaurus/plugin-debug` |
|
||||
| | `@docusaurus/plugin-google-analytics` |
|
||||
| | `@docusaurus/plugin-google-gtag` |
|
||||
| | `@docusaurus/plugin-sitemap` |
|
||||
|
|
@ -92,17 +93,19 @@ module.exports = {
|
|||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
// Debug defaults to true in dev, false in prod
|
||||
debug: undefined,
|
||||
// Will be passed to @docusaurus/theme-classic.
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
},
|
||||
// Will be passed to @docusaurus/plugin-content-docs
|
||||
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
|
||||
docs: {},
|
||||
// Will be passed to @docusaurus/plugin-content-blog
|
||||
// Will be passed to @docusaurus/plugin-content-blog (false to disable)
|
||||
blog: {},
|
||||
// Will be passed to @docusaurus/plugin-content-pages
|
||||
// Will be passed to @docusaurus/plugin-content-pages (false to disable)
|
||||
pages: {},
|
||||
// Will be passed to @docusaurus/plugin-content-sitemap
|
||||
// Will be passed to @docusaurus/plugin-content-sitemap (false to disable)
|
||||
sitemap: {},
|
||||
},
|
||||
],
|
||||
|
|
@ -135,11 +138,11 @@ module.exports = {
|
|||
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
|
||||
|
||||
| Themes | Plugins |
|
||||
| ---------------------------------- | ------------------------------------- |
|
||||
| ----------------------------- | ---------------------------------- |
|
||||
| `@docusaurus/theme-bootstrap` | `@docusaurus/plugin-content-docs` |
|
||||
| | `@docusaurus/plugin-content-blog` |
|
||||
| | `@docusaurus/plugin-content-pages` |
|
||||
|
||||
| | `@docusaurus/plugin-debug` |
|
||||
|
||||
To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `docs` for `@docusaurus/theme-bootstrap`, pass them in the preset field, like this:
|
||||
|
||||
|
|
@ -149,15 +152,18 @@ module.exports = {
|
|||
[
|
||||
'@docusaurus/preset-bootstrap',
|
||||
{
|
||||
// Will be passed to @docusaurus/plugin-content-docs
|
||||
// Debug defaults to true in dev, false in prod
|
||||
debug: undefined,
|
||||
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
|
||||
docs: {},
|
||||
// Will be passed to @docusaurus/plugin-content-blog
|
||||
// Will be passed to @docusaurus/plugin-content-blog (false to disable)
|
||||
blog: {},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
This preset is work in progress
|
||||
|
|
|
|||
|
|
@ -966,3 +966,37 @@ The module should have a `default` function export, and receives some params.
|
|||
Adds an entry before the Docusaurus app so that registration can happen before the app runs. The default `registerSW.js` file is enough for simple registration.
|
||||
|
||||
Passing `false` will disable registration entirely.
|
||||
|
||||
### `@docusaurus/plugin-debug`
|
||||
|
||||
The debug plugin will display useful debug informations at [http://localhost:3000/\_\_docusaurus/debug](http://localhost:3000/__docusaurus/debug).
|
||||
|
||||
It is mostly useful for plugin authors, that will be able to inspect more easily the content of the `.docusaurus` folder (like the creates routes), but also be able to inspect data structures that are never written to disk, like the plugin data loaded through the `contentLoaded` lifecycle.
|
||||
|
||||
:::note
|
||||
|
||||
If you report a bug, we will probably ask you to have this plugin turned on in the production, so that we can inspect your deployment config more easily.
|
||||
|
||||
If you don't have any sensitive information, you can keep it on in production [like we do](http://v2.docusaurus.io/__docusaurus/debug).
|
||||
|
||||
:::
|
||||
|
||||
**Installation**
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save @docusaurus/plugin-debug
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
|
||||
|
||||
By default, it's enabled in dev, and disabled in prod, to avoid exposing potentially sensitive informations.
|
||||
|
||||
:::
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: ['@docusaurus/plugin-debug'],
|
||||
};
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue