How to Use the Docusaurus Debug Plugin to Diagnose Build Issues

The Docusaurus debug plugin (@docusaurus/plugin-debug) exposes a debugging UI at /__docusaurus/debug that lets you inspect configuration, routes, content, and global data to troubleshoot build problems.

When static site generation fails or routes behave unexpectedly in the facebook/docusaurus repository, the Docusaurus debug plugin provides a built-in diagnostic interface. This official plugin renders a React-based debugging UI that exposes the internal state of your site, making it invaluable for plugin authors and developers tracing build-time issues.

What the Docusaurus Debug Plugin Exposes

The plugin registers routes under /__docusaurus/debug that render a navigation layout defined in [packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.tsx). This DebugLayout component provides access to six diagnostic pages:

• /__docusaurus/debug – Displays the Config page (DebugConfig) showing your docusaurus.config.js values as rendered by [DebugConfig/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.tsx).
• /__docusaurus/debug/metadata – Shows site-wide metadata via DebugSiteMetadata in [DebugSiteMetadata/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/index.tsx).
• /__docusaurus/debug/registry – Lists the component registry (DebugRegistry) as implemented in [DebugRegistry/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/index.tsx).
• /__docusaurus/debug/routes – Enumerates all router routes (DebugRoutes) generated during the build, rendered by [DebugRoutes/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/index.tsx).
• /__docusaurus/debug/content – Renders the full content model (DebugContent) including processed Markdown/MDX and sidebar data via [DebugContent/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx).
• /__docusaurus/debug/globalData – Displays the global data object (DebugGlobalData) in [DebugGlobalData/index.tsx](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.tsx).

Each page uses helper components like DebugJsonView to render collapsible JSON views. The TypeScript definitions in [plugin-debug.d.ts](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/plugin-debug.d.ts) declare these theme components, while the implementations live under src/theme/.

Enabling the Docusaurus Debug Plugin

Via the Classic Preset

Most Docusaurus sites use the classic preset, which includes the debug plugin automatically in development but disables it in production. To force enable it in production builds for troubleshooting, set the debug option to true as documented in plugin-debug.mdx:

// docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Enable the debug plugin in production builds
        debug: true,
      },
    ],
  ],
};

As a Standalone Plugin

For custom configurations without the classic preset, add @docusaurus/plugin-debug directly to your plugins array. Guard it with an environment check to restrict it to development:

// docusaurus.config.js
export default {
  plugins: [
    // Only load in non-production environments
    process.env.NODE_ENV !== 'production' && '@docusaurus/plugin-debug',
  ].filter(Boolean),
};

To enable it unconditionally in production using the standalone method, omit the environment guard:

// docusaurus.config.js
export default {
  plugins: ['@docusaurus/plugin-debug'],
};

The plugin accepts no configuration options; its presence alone activates the debugging interface.

Investigating Build Issues with the Debug UI

Use this workflow to diagnose problems using the Docusaurus debug plugin interface:

1. Start the development server (npm run start or yarn start) or build the site with the plugin enabled.
2. Navigate to http://localhost:3000/__docusaurus/debug (adjust the port and base URL as needed).
3. Inspect the Config page to verify that docusaurus.config.js values loaded correctly, including theme and plugin configurations.
4. Check the Routes page to see the generated route hierarchy. This helps when pages return 404s or navigate incorrectly.
5. Review the Content page to examine the AllContent object. This reveals processed Markdown/MDX files, sidebar structures, and plugin-provided content that may be missing or malformed.
6. Examine Global Data to verify data passing between plugins, which often causes hydration mismatches in production builds.

Security Warning: The debug UI exposes internal site data including configuration details and file paths. As warned in the official Docusaurus documentation, disable the plugin in public production builds unless actively troubleshooting, as the exposed data could reveal sensitive implementation details.

Summary

• The Docusaurus debug plugin (@docusaurus/plugin-debug) exposes internal site state at /__docusaurus/debug through a dedicated React interface.
• The plugin renders six diagnostic views—Config, Metadata, Registry, Routes, Content, and Global Data—via components in packages/docusaurus-plugin-debug/src/theme/.
• Enable it through the classic preset's debug: true option or by adding it manually to the plugins array.
• Use the Content and Routes pages to trace missing files or routing errors during builds.
• Never leave the debug plugin enabled in public-facing production environments due to data exposure risks.

Frequently Asked Questions

How do I access the Docusaurus debug UI?

After enabling @docusaurus/plugin-debug and starting your development server, visit http://localhost:3000/__docusaurus/debug (adjust for your base URL if configured). The interface appears as a navigation bar with links to Config, Routes, Content, and other diagnostic pages rendered by the plugin's theme components.

Is the debug plugin safe to use in production?

The debug plugin exposes internal configuration, file paths, and data structures that could aid attackers in understanding your site architecture. While you can enable it in production by setting debug: true in the classic preset or removing environment guards from the standalone plugin configuration, you should disable it immediately after troubleshooting to prevent information leakage.

What information does the Docusaurus debug plugin expose?

The plugin reveals the complete site configuration from docusaurus.config.js, the component registry, all generated router routes, the full content model including processed Markdown/MDX and sidebars, and the global data object shared between plugins. This data is rendered via React components like DebugConfig and DebugContent defined in the plugin's src/theme/ directory.

Can I configure options for the debug plugin?

No, the Docusaurus debug plugin accepts no configuration options. According to the source code in plugin-debug.d.ts and the implementation files, the plugin activates solely based on its presence in the presets or plugins array. You cannot customize the routes or the displayed data through plugin options.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}