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>

packages/docusaurus-plugin-debug/src/index.ts

@@ -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() {

packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.js

@@ -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>
   );
 }

packages/docusaurus-plugin-debug/src/theme/DebugConfig/styles.module.css

@@ -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.
- */
-

packages/docusaurus-plugin-debug/src/theme/DebugContent/index.js

@@ -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>
+    <code>{pluginId}</code>
-    <div
+    <DebugJsonView src={pluginInstanceContent} collapseDepth="2" />
-      style={{
-        marginTop: 10,
-        padding: 10,
-        border: 'thin cyan solid',
-        borderRadius: 5,
-        backgroundColor: 'lightgrey',
-      }}>
-      <DebugJsonView src={pluginInstanceContent} />
-    </div>
   </section>
 );
 
 const PluginContent = ({pluginName, pluginContent}) => {
-  const [visible, setVisible] = useState(true);
   return (
     <section style={{marginBottom: 60}}>
-      <h3 onClick={() => setVisible((v) => !v)} style={{cursor: 'pointer'}}>
+      <h3>{pluginName}</h3>
-        {pluginName}
-      </h3>
-      {visible && (
       <div>
         {Object.entries(pluginContent)
           // filter plugin instances with no content
@@ -50,7 +37,6 @@ const PluginContent = ({pluginName, pluginContent}) => {
             );
           })}
       </div>
-      )}
     </section>
   );
 };

packages/docusaurus-plugin-debug/src/theme/DebugContent/styles.module.css

@@ -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.
- */
-

packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.js

@@ -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;

packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.js

@@ -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
+        // Non-root elements that are larger than 50 fields are collapsed
-        return field.name !== RootName;
+        return field.name !== RootName && Object.keys(field.src).length > 50;
       }}
+      collapsed={collapseDepth}
+      groupArraysAfterLength="5"
+      enableClipboard={false}
+      displayDataTypes={false}
     />
   );
 }

packages/docusaurus-plugin-debug/src/theme/DebugJsonView/styles.module.css

@@ -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.
- */
-

packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.js

@@ -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={styles.navlink}
-    className="button button--primary"
     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>
   );
 }

packages/docusaurus-plugin-debug/src/theme/DebugLayout/styles.module.css

@@ -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);
+  }
+}

packages/docusaurus-plugin-debug/src/theme/DebugMetadata/styles.module.css

@@ -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.
- */
-

packages/docusaurus-plugin-debug/src/theme/DebugRegistry/index.js

@@ -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}>
+          <li key={aliasedPath} className={styles.listItem}>
-            <div>Aliased Path: {aliasedPath}</div>
+            <div style={{marginBottom: '10px'}}>
-            <div>Resolved Path: {resolved}</div>
+              Aliased Path: <code>{aliasedPath}</code>
+            </div>
+            <div>
+              Resolved Path: <code>{resolved}</code>
+            </div>
           </li>
         ))}
       </ul>

packages/docusaurus-plugin-debug/src/theme/DebugRegistry/styles.module.css

@@ -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;
+}

packages/docusaurus-plugin-debug/src/theme/DebugRoutes/index.js

@@ -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>
+      <ul className={styles.list}>
-        {routes.map(({path, exact}) => (
+        {routes.map(({path, exact, routes: childRoutes}) => (
-          <li key={path}>
+          <li key={path} className={styles.listItem}>
-            <div>Route: {path}</div>
+            <div className={styles.route}>
-            <div>Is exact: {String(Boolean(exact))}</div>
+              <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>

packages/docusaurus-plugin-debug/src/theme/DebugRoutes/styles.module.css

@@ -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;
+}

packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/index.js

@@ -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>
+      <div>
-      <ul>
+        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}>
+            <li key={name} className={styles.listItem}>
-              <div>Name: {name}</div>
-              <div>Type: {versionInformation.type}</div>
               {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>
           ),
         )}

packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/styles.module.css

@@ -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;
+}

website/docs/presets.md

@@ -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

website/docs/using-plugins.md

@@ -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'],
+};
+```