WordPress ships no built-in way to embed a plugin's own documentation in the editor, but the block editor's component model makes it possible to put answers where users already are. The approach below builds a paginated popup — a <Guide> — inside a plugin's Custom Post Type screens. WordPress already uses a <Guide> for the editor's first-run welcome modal: a container of content split into pages. Rather than reinventing it, we can reuse it.

The target: a scoped documentation panel

The plugin in question is a GraphQL server for WordPress with a broad set of CPTs, each edited through custom blocks defined via templates. Two blocks matter here: "GraphiQL client" for entering a GraphQL query, and "Persisted query options" for customizing execution behavior. Because writing GraphQL is nontrivial, the guide is attached to the editor screen for that CPT, exposed through the Document settings as a panel labeled "Welcome Guide." Opening the panel reveals a link that launches the modal.

Screenshot showing the WordPress editor with the document settings panel open in the right column. a welcome guide tab is highlighted in the settings.

Inside the modal, the first page carries a tutorial video for the CPT; the remaining pages walk through every available option.

Close-up screenshot of the welcome guide tab opened, revealing a link that says "Open Guide: Creating Persisted Queries."
Screenshot showing the custom modal open in the block editor and containing an embedded video on how to use the plugin.

The trigger link sits in the Document settings panel:

const { registerPlugin } = wp.plugins;
const { PluginDocumentSettingPanel } = wp.editPost;
 
const PluginDocumentSettingPanelDemo = () => (
  <PluginDocumentSettingPanel
    name="custom-panel"
    title="Custom Panel"
    className="custom-panel"
  >
    Custom Panel Contents
  </PluginDocumentSettingPanel>
);
registerPlugin( 'plugin-document-setting-panel-demo', {
  render: PluginDocumentSettingPanelDemo,
  icon: 'palmtree',
} );

Building the panel script

Starting with WordPress 5.4, <PluginDocumentSettingPanel> adds a panel to Document settings. It is not a block, which creates a practical snag: no block scaffolding command applies to it, and the snippet is JSX, so it needs a JavaScript build step. The compiled ES5 equivalent exists and can be enqueued like any other script, but that sacrifices the ESNext/JSX toolchain.

The way around it is that registering a script and registering a block differ only at registration. A block is registered through register_block_type; a plain script through wp_register_script. So scaffold as if for a block, then register the output as an ordinary script and keep the webpack configuration. Available scaffolding tools:

  • wp scaffold block (WP-CLI)
  • Ahmad Awais's create-guten-block
  • The official @wordpress/create-block package

The last option was chosen because the Gutenberg team maintains it. Running it generates a single-block plugin with an entry PHP file; that code is copied into the plugin and adjusted to register a regular script instead of a block, with the CSS files dropped. The generated package.json comes along, and src/index.js is replaced with the ESNext code that registers <PluginDocumentSettingPanel>. npm start (or npm run build for production) compiles it into build/index.js. Dependencies and the webpack configuration tied to @wordpress/scripts can be refreshed later with npm run packages-update.

The runtime dependency gap

One detail needs manual handling. <PluginDocumentSettingPanel> is not statically imported — it comes from the global wp.editPost, so its dependency never lands in the auto-generated index.asset.php. The wp-edit-post script must therefore be added as an explicit dependency at registration so it loads first.

This follows from how the Dependency Extraction Webpack Plugin translates package names into runtime handles: "@wordpress/" becomes "wp-", so "@wordpress/edit-post" maps to wp-edit-post, and that is where the wp.editPost variable is defined. Had the component been directly importable, that dependency would be handled automatically.

Restricting the panel to one CPT

The documentation belongs to a specific CPT, so the panel must not appear on other post types. Ryan Welcher, who created <PluginDocumentSettingPanel>, describes restricting it at registration time in the panel's render callback, with useSelect offered as an alternative to withSelect. That approach still enqueues the JavaScript everywhere; the file runs purely to hide itself where it is unneeded, costing performance for no function.

A PHP-side solution avoids this. First determine the post type of the object being created or edited:

var el = wp.element.createElement;
var __ = wp.i18n.__;
var registerPlugin = wp.plugins.registerPlugin;
var PluginDocumentSettingPanel = wp.editPost.PluginDocumentSettingPanel;


function MyDocumentSettingPlugin() {
  return el(
    PluginDocumentSettingPanel,
    {
      className: 'my-document-setting-plugin',
      title: 'My Panel',
    },
    __( 'My Document Setting Panel' )
  );
}


registerPlugin( 'my-document-setting-plugin', {
  render: MyDocumentSettingPlugin
} );

Then register the script only when that post type matches the target CPT:

wp_register_script($blockScriptName, $blockScriptURL, $dependencies, $version);
register_block_type('my-namespace/my-block', [
  'editor_script' => $blockScriptName,
]);

The approach is arguably hacky, but it works and skips the wasted JavaScript load.

Assembling the guide

The <Guide> inside <GuidePage> instances is the basis. It was found two ways: searching the Gutenberg source for text from the editor's own modal, which leads to the welcome-guide implementation, and browsing Gutenberg's Storybook, an interactive catalogue of every available component with example source (stories) showing how props customize a component. The <Guide> README in the @wordpress/components package supplies the remaining details. The editor's guide was copied as a starting point.

What the copied pattern does not cover is launching the guide on click — for that, React state is required. The component uses the useState hook, with a button whose listener opens the modal. React knowledge is a hard prerequisite for substantial block editor work.

Content for each page is straightforward HTML; other components can be embedded as well. In this build three <GuidePage> instances were used: a video tutorial first, then two pages of detailed instructions. A reusable content component, <CacheControlDescription>, was factored out to describe HTTP caching, which leaves the door open to surface it outside the guide as noted later.

wp_register_script($scriptName, $scriptURL, $dependencies, $version);
wp_enqueue_script($scriptName);
npm init @wordpress/block

Known rough edges

  • A video embedded inside <Guide> proved unworkable: pressing play closes the guide, presumably because the <iframe> sits outside the guide's boundaries. The workaround was uploading the video to S3 and serving it through <video>.
  • Page transitions are not smooth. The editor's own modal looks fine because its pages share a similar height; this guide's do not, so the change is abrupt.
  • Button hover styling needs improvement, and would have to come from the Gutenberg team for its own purposes.

None of these block the core functionality.

Reusing guide content elsewhere

Because page content was built as an autonomous component, <CacheControlDescription> can appear inside a <GuidePage> or, separately, inside a <Modal>. A good pattern is to show the trigger only while the user is working with the relevant block, toggling the button on the value of isSelected. The component is then added to the appropriate control.

/**
 * Registers all block assets so that they can be enqueued through the block editor
 * in the corresponding context.
 *
 * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/applying-styles-with-stylesheets/
 */
function my_namespace_my_block_block_init() {
  $dir = dirname( __FILE__ );


  $script_asset_path = "$dir/build/index.asset.php";
  if ( ! file_exists( $script_asset_path ) ) {
    throw new Error(
      'You need to run `npm start` or `npm run build` for the "my-namespace/my-block" block first.'
    );
  }
  $index_js     = 'build/index.js';
  $script_asset = require( $script_asset_path );
  wp_register_script(
    'my-namespace-my-block-block-editor',
    plugins_url( $index_js, __FILE__ ),
    $script_asset['dependencies'],
    $script_asset['version']
  );


  $editor_css = 'editor.css';
  wp_register_style(
    'my-namespace-my-block-block-editor',
    plugins_url( $editor_css, __FILE__ ),
    array(),
    filemtime( "$dir/$editor_css" )
  );


  $style_css = 'style.css';
  wp_register_style(
    'my-namespace-my-block-block',
    plugins_url( $style_css, __FILE__ ),
    array(),
    filemtime( "$dir/$style_css" )
  );


  register_block_type( 'my-namespace/my-block', array(
    'editor_script' => 'my-namespace-my-block-block-editor',
    'editor_style'  => 'my-namespace-my-block-block-editor',
    'style'         => 'my-namespace-my-block-block',
  ) );
}
add_action( 'init', 'my_namespace_my_block_block_init' );
function my_script_init() {
  $dir = dirname( __FILE__ );


  $script_asset_path = "$dir/build/index.asset.php";
  if ( ! file_exists( $script_asset_path ) ) {
    throw new Error(
      'You need to run `npm start` or `npm run build` for the "my-script" script first.'
    );
  }
  $index_js     = 'build/index.js';
  $script_asset = require( $script_asset_path );
  wp_register_script(
    'my-script',
    plugins_url( $index_js, __FILE__ ),
    $script_asset['dependencies'],
    $script_asset['version']
  );
  wp_enqueue_script(
    'my-script'
  );
}
add_action( 'init', 'my_script_init' );
{
  "name": "my-block",
  "version": "0.1.0",
  "description": "This is my block",
  "author": "The WordPress Contributors",
  "license": "GPL-2.0-or-later",
  "main": "build/index.js",
  "scripts": {
    "build": "wp-scripts build",
    "format:js": "wp-scripts format-js",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "start": "wp-scripts start",
    "packages-update": "wp-scripts packages-update"
  },
  "devDependencies": {
    "@wordpress/scripts": "^9.1.0"
  }
}
$dependencies = array_merge(
  $script_asset['dependencies'],
  [
    'wp-edit-post',
  ]
);
wp_register_script(
  'my-script',
  plugins_url( $index_js, __FILE__ ),
  $dependencies,
  $script_asset['version']
);