From 9857f7b2b50aae94f54f7d70fa1170962904eba8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Wed, 2 Sep 2020 15:42:34 +0200 Subject: [PATCH] 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 9c43c9f7fbf1c51a228a495dcc081e1ad383e51d. * Set colors to dark theme * Add plugin debug doc + minor fixes + expose global data * more debug plugin doc Co-authored-by: Drewbi --- packages/docusaurus-plugin-debug/src/index.ts | 8 ++- .../src/theme/DebugConfig/index.js | 4 +- .../src/theme/DebugConfig/styles.module.css | 7 -- .../src/theme/DebugContent/index.js | 54 ++++++--------- .../src/theme/DebugContent/styles.module.css | 7 -- .../src/theme/DebugGlobalData/index.js | 24 +++++++ .../src/theme/DebugJsonView/index.js | 17 ++++- .../src/theme/DebugJsonView/styles.module.css | 7 -- .../src/theme/DebugLayout/index.js | 18 +++-- .../src/theme/DebugLayout/styles.module.css | 69 +++++++++++++++++++ .../src/theme/DebugMetadata/styles.module.css | 7 -- .../src/theme/DebugRegistry/index.js | 14 ++-- .../src/theme/DebugRegistry/styles.module.css | 11 +++ .../src/theme/DebugRoutes/index.js | 22 ++++-- .../src/theme/DebugRoutes/styles.module.css | 19 +++++ .../index.js | 22 +++--- .../theme/DebugSiteMetadata/styles.module.css | 31 +++++++++ website/docs/presets.md | 30 ++++---- website/docs/using-plugins.md | 34 +++++++++ 19 files changed, 301 insertions(+), 104 deletions(-) delete mode 100644 packages/docusaurus-plugin-debug/src/theme/DebugConfig/styles.module.css delete mode 100644 packages/docusaurus-plugin-debug/src/theme/DebugContent/styles.module.css create mode 100644 packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.js delete mode 100644 packages/docusaurus-plugin-debug/src/theme/DebugJsonView/styles.module.css delete mode 100644 packages/docusaurus-plugin-debug/src/theme/DebugMetadata/styles.module.css rename packages/docusaurus-plugin-debug/src/theme/{DebugMetadata => DebugSiteMetadata}/index.js (58%) create mode 100644 packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/styles.module.css diff --git a/packages/docusaurus-plugin-debug/src/index.ts b/packages/docusaurus-plugin-debug/src/index.ts index 1ca9d6f0e1af..ac406dbf8d01 100644 --- a/packages/docusaurus-plugin-debug/src/index.ts +++ b/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() { diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.js index 99a4191bc8ea..83ec1e386f8a 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.js +++ b/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 (

Site config

-
{JSON.stringify(siteConfig, null, 2)}
+
); } diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugConfig/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugConfig/styles.module.css deleted file mode 100644 index 99ba01cb7753..000000000000 --- a/packages/docusaurus-plugin-debug/src/theme/DebugConfig/styles.module.css +++ /dev/null @@ -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. - */ - diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.js index c79f7899c4ed..e798dd0f7d61 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.js +++ b/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.js @@ -5,52 +5,38 @@ * 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}) => (
-

{`>> ${pluginId}`}

-
- -
+ {pluginId} +
); const PluginContent = ({pluginName, pluginContent}) => { - const [visible, setVisible] = useState(true); return (
-

setVisible((v) => !v)} style={{cursor: 'pointer'}}> - {pluginName} -

- {visible && ( -
- {Object.entries(pluginContent) - // filter plugin instances with no content - .filter( - ([_pluginId, pluginInstanceContent]) => !!pluginInstanceContent, - ) - .map(([pluginId, pluginInstanceContent]) => { - return ( - - ); - })} -
- )} +

{pluginName}

+
+ {Object.entries(pluginContent) + // filter plugin instances with no content + .filter( + ([_pluginId, pluginInstanceContent]) => !!pluginInstanceContent, + ) + .map(([pluginId, pluginInstanceContent]) => { + return ( + + ); + })} +
); }; diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugContent/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugContent/styles.module.css deleted file mode 100644 index 99ba01cb7753..000000000000 --- a/packages/docusaurus-plugin-debug/src/theme/DebugContent/styles.module.css +++ /dev/null @@ -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. - */ - diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.js new file mode 100644 index 000000000000..84b4c7599c1f --- /dev/null +++ b/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 ( + +

Global data

+ +
+ ); +} + +export default DebugMetadata; diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.js index 558b31c71c50..f8ec854d97cc 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.js +++ b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.js @@ -25,17 +25,28 @@ const BrowserOnlyReactJson = (props) => { ); }; -function DebugJsonView({src}) { +function DebugJsonView({src, collapseDepth}) { return ( { // 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} /> ); } diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/styles.module.css deleted file mode 100644 index 99ba01cb7753..000000000000 --- a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/styles.module.css +++ /dev/null @@ -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. - */ - diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.js index 02c2eb7f869b..9e281e011b10 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.js +++ b/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}) => ( + exact + activeStyle={{ + backgroundColor: '#363739', + }}> {children} ); @@ -24,14 +25,17 @@ const DebugNavLink = ({to, children}) => ( function DebugLayout({children}) { return (
-
); } diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugLayout/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugLayout/styles.module.css index b5c0e33b4a5b..cd076b67a13d 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugLayout/styles.module.css +++ b/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); + } +} diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugMetadata/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugMetadata/styles.module.css deleted file mode 100644 index 99ba01cb7753..000000000000 --- a/packages/docusaurus-plugin-debug/src/theme/DebugMetadata/styles.module.css +++ /dev/null @@ -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. - */ - diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/index.js index f10a53a8a6f2..5df4c763fc58 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/index.js +++ b/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 ( - {' '}

Registry

-
    +
      {Object.values(registry).map(([, aliasedPath, resolved]) => ( -
    • -
      Aliased Path: {aliasedPath}
      -
      Resolved Path: {resolved}
      +
    • +
      + Aliased Path: {aliasedPath} +
      +
      + Resolved Path: {resolved} +
    • ))}
    diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/styles.module.css index 99ba01cb7753..590719949918 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/styles.module.css +++ b/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; +} diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/index.js index 5eedd036f41a..8ffa8c0505ea 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/index.js +++ b/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 (

    Routes

    -
      - {routes.map(({path, exact}) => ( -
    • -
      Route: {path}
      -
      Is exact: {String(Boolean(exact))}
      +
        + {routes.map(({path, exact, routes: childRoutes}) => ( +
      • +
        + {path} +
        +
        + Is exact: {String(Boolean(exact))} +
        + {childRoutes && ( +
        + Child Routes: + +
        + )}
      • ))}
      diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/styles.module.css index 99ba01cb7753..2c0ff2f03883 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/styles.module.css +++ b/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; +} diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugMetadata/index.js b/packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/index.js similarity index 58% rename from packages/docusaurus-plugin-debug/src/theme/DebugMetadata/index.js rename to packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/index.js index 9cb98a2e1e73..c78e03a1472e 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugMetadata/index.js +++ b/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 (

      Site Metadata

      -
      Docusaurus Version: {siteMetadata.docusaurusVersion}
      - Site Version: {siteMetadata.siteVersion || 'No version specified'} + Docusaurus Version: {siteMetadata.docusaurusVersion}
      -

      Plugins and themes:

      -
        +
        + Site Version:{' '} + {siteMetadata.siteVersion || 'No version specified'} +
        +

        Plugins and themes

        +
          {Object.entries(siteMetadata.pluginVersions).map( ([name, versionInformation]) => ( -
        • -
          Name: {name}
          -
          Type: {versionInformation.type}
          +
        • {versionInformation.version && ( -
          Version: {versionInformation.version}
          +
          + {versionInformation.version} +
          )} +
          {name}
          +
          Type: {versionInformation.type}
        • ), )} diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/styles.module.css b/packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/styles.module.css new file mode 100644 index 000000000000..37f3e666f6a2 --- /dev/null +++ b/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; +} diff --git a/website/docs/presets.md b/website/docs/presets.md index 23e9129bd4f4..80531f71f2b1 100644 --- a/website/docs/presets.md +++ b/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: {}, }, ], @@ -134,12 +137,12 @@ 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` | - +| 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 diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index d01a9992782c..560f7e64fbe4 100644 --- a/website/docs/using-plugins.md +++ b/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'], +}; +```