Skip to content

About

Use the Gutenberg block editor anywhere in WordPress.

Resources

Stars

2 stars

Watchers

1 watching

Forks

 
 

Latest commit

 

History

384 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Blocks Everywhere

110600033-c625d880-8183-11eb-9609-70ab7390c0d9

Switches the default WordPress editor for comments, bbPress, and BuddyPress to use Gutenberg. Admin moderation is also upgraded to use Gutenberg, and blocks are processed on the front end.

For extra security the list of available blocks is determined by the allowed tags from WordPress. Disallowed blocks, including nested blocks, are removed on save and render. Customize the server allowlist with blocks_everywhere_allowed_blocks, which receives the block list and context type.

Gutenberg is not bundled and instead is side-loaded from WordPress. For better compatibility you should use the plugin version of Gutenberg, which is typically several versions ahead of the one included in WordPress.

The condition of the Gutenberg replacements are:

  • bbPress - good (requires bbPress 2.6+)
  • comments - alright
  • BuddyPress - needs a lot of work

The plugin mounts Gutenberg directly against the @wordpress/block-editor primitives shipped with WordPress core (no wrapping editor framework). Earlier releases used Isolated Block Editor; that dependency was removed in v2.2.0 and the embedded shell now renders directly against current Gutenberg.

Blocks Everywhere can be downloaded from WordPress.org:

https://wordpress.org/plugins/blocks-everywhere/

Caveats

Gutenberg is placed directly on the page along with your post, forum, etc. This means the contents of the editor will look like the page they will appear on. However, it also means that styles from the page may affect the editor.

Currently we don't have a perfect way of seperating these styles and it is possible that styles from the page or from Gutenberg may affect the other. If you are using this plugin then it is expected that you will be able to fix any differences as appropriate for your site.

The loading of Gutenberg will also increase the page size of any page it is loaded on. You should be aware of this and willing to accept this in the context of your site.

Usage

To enable Blocks Everywhere you need to add the relevant define to wp-config.php:

define( 'BLOCKS_EVERYWHERE_COMMENTS', true );
define( 'BLOCKS_EVERYWHERE_BBPRESS', true );
define( 'BLOCKS_EVERYWHERE_BUDDYPRESS', true );

You can also use the WordPress filter blocks_everywhere_comments, blocks_everywhere_bbpress, and blocks_everywhere_buddypress.

To enable back-end editing in bbPress:

define( 'BLOCKS_EVERYWHERE_ADMIN', true );

Or use the filter blocks_everywhere_admin. Back-end editing is restricted to users with the manage_options capability (can be changed with the blocks_everywhere_admin_cap filter).

To enable conversion of blocks in email:

define( 'BLOCKS_EVERYWHERE_EMAIL', true );

Or use the filter blocks_everywhere_email.

To enable Gutenberg when editing bbPress forums, topics, and replies you can use:

define( 'BLOCKS_EVERYWHERE_BBPRESS_ADMIN', true );

Or use blocks_everywhere_bbpress_admin

Settings

Some settings are available through the settings object, which is filterable with blocks_everywhere_editor_settings.

allowUrlEmbed - Enable or disable auto-embed for URLs replaceParagraphCode - Enable the custom paragraph that converts HTML and PHP code into a code block pastePlainText - Convert all pasted content to plain text patchEmoji - set to true to stop twemoji from affecting the editor blocksEverywhere.allowEmbeds - List of enabled embeds blocksEverywhere.blocks.allowBlocks - Blocks offered in the editor. Use blocks_everywhere_allowed_blocks to permit blocks on save and render. blocksEverywhere.className - String of classes to be assigned to the editor. blocksEverywhere.__experimentalOnChange - An optional callback that is triggered when the blocks are changed. blocksEverywhere.__experimentalOnInput - An optional callback that is triggered when text is input. blocksEverywhere.__experimentalOnSelection - An optional callback when a block is selected. blocksEverywhere.toolbar - Per-primitive opt-out for the editor toolbar (see below). Default matches the upstream wp-admin post editor. blocksEverywhere.chrome - Editor shell region configuration (see below). Lets hosts enable extra chrome slots or hide built-in chrome without replacing the editor shell.

Toolbar configuration

blocksEverywhere.toolbar accepts a map of per-primitive booleans. Defaults match the upstream wp-admin post editor — every primitive is enabled. Consumers opt OUT of individual primitives; they never need to opt IN. Any key left unset is treated as true.

Key Default Description
inserter true Document-level + block inserter button. Effectively suppressed when a persistent detached sidebar is mounted (the sidebar already exposes the inserter).
undo true Undo button. Delegates to the core editor history; no-op when no entity is being edited.
redo true Redo button. Delegates to the core editor history; no-op when no entity is being edited.
listView true List view toggle + dropdown panel of the editor's blocks.
blockTools true Selected-block format toolbar (the contextual ¶ B I link row shown when a block is selected).

Default (matches wp-admin):

add_filter( 'blocks_everywhere_editor_settings', function ( $settings ) {
	// No toolbar config needed — defaults to the full upstream toolbar shape.
	return $settings;
} );

Opt out of specific primitives:

add_filter( 'blocks_everywhere_editor_settings', function ( $settings ) {
	$settings['blocksEverywhere']['toolbar'] = array(
		'undo'     => false,
		'redo'     => false,
		'listView' => false,
		// `inserter` and `blockTools` default to true.
	);
	return $settings;
} );

Chrome configuration and slots

blocksEverywhere.chrome controls editor shell regions. Existing editor chrome stays unchanged by default: the primary toolbar and footer render, while optional host-owned regions are disabled until enabled.

Key Default Description
mode inline Adds a layout class for inline, full-height, modal, or compact editor shells.
fullscreen false Enables the built-in fullscreen toggle and window controls row. Pass { enabled, defaultActive, active, onChange } for host-controlled state.
topBar false Enables the topBar and windowControls slots above the primary toolbar.
toolbar true Shows the primary toolbar row. Set false when a host fully replaces toolbar chrome.
preview false Shows WordPress's native frontend Preview control when settings.postEntity identifies an existing canonical post.
secondaryToolbar false Enables a host-owned row below the primary toolbar.
footer true Shows the footer slot.
documentSidebar false Enables a persistent host-owned panel before the canvas.
inserterSidebar false Enables a persistent host-owned panel after the canvas.

Register fills with window.blocksEverywhere.registerSlotFill( slot, renderFn ). Supported slots are heading, toolbar, actions, footer, topBar, windowControls, secondaryToolbar, documentSidebar, and inserterSidebar.

add_filter( 'blocks_everywhere_editor_settings', function ( $settings ) {
	$settings['blocksEverywhere']['chrome'] = array(
		'mode'            => 'modal',
		'fullscreen'      => true,
		'topBar'          => true,
		'secondaryToolbar' => true,
		'documentSidebar' => true,
	);

	$settings['blocksEverywhere']['toolbar'] = array(
		'undo'     => false,
		'redo'     => false,
		'listView' => false,
	);

	return $settings;
} );

Native frontend preview is opt-in because textarea, comment, bbPress, and generic entity mounts do not represent WordPress posts. For an existing canonical post, provide a positive post ID and enable preview:

window.blocksEverywhere.mountEditor( textarea, {
	settings: {
		postEntity: { type: 'post', id: 123 },
		blocksEverywhere: {
			chrome: { preview: true },
		},
	},
} );

This control uses the public @wordpress/editor PostPreviewButton. WordPress saves or autosaves current edits and opens the core-generated frontend preview URL with the active theme, templates, rendering filters, and authorization. It is different from editor-canvas theme styling, which only approximates content appearance inside the editor. The control remains unavailable until the host creates a draft and remounts with its positive post ID; WordPress core hides it for non-viewable post types and disables it when the post cannot be saved.

Theme compatibility

Gutenberg is placed directly on the page along with your post, forum, etc. This means the contents of the editor will look like the page they will appear on. However, it also means that styles from the page may affect the editor.

We don't have a perfect way of separating these styles and it is possible that styles from the page or from Gutenberg may affect the other. If you are using this plugin then it is expected that you will be able to fix any differences as appropriate for your site.

A theme compatibility option is provided which might help. You can use this with:

define( 'BLOCKS_EVERYWHERE_THEME_COMPAT', true );

Or using the filter blocks_everywhere_theme_compat.

It provides some overrides for common theme issues. However, it is generally better not to require overrides so if you are able to modify your theme and make CSS more specific then that is the best route.

For example, rather than defining a global button style (which would then affect Gutenberg), make the style specific to the areas where a button will be used.

Using Content Embed block

Content Embed block uses REST API to fetch content to be embedded. This means that site contains bbPress topics to embed should have topic REST API enabled.

Blocks Everywhere enables topic REST API on its own, so if the site with bbPress have this plugin installed and configured, its topics can be embedded.

To enable Content Embed on save, render, and in the editor, add it to the server allowlist:

add_filter( 'blocks_everywhere_allowed_blocks', function( $blocks ) {
	$blocks[] = 'blocks-everywhere/support-content';
	return $blocks;
} );

To enable REST API for forum topics, use next filters:

add_filter( 'blocks_everywhere_admin', '__return_true' );
add_filter( 'blocks_everywhere_admin_cap', '__return_empty_string' );

REST API is only used when creating content embed and not used to view it. So blocks_everywhere_admin_cap can return specific capability to limit users who will have access to API.

KSES

Gutenberg outputs HTML content and this may be affected by KSES (WordPress HTML sanitisation), as well as other functions.

The plugin provides some modifications to this so it works fine with basic blocks. You may run into problems if you are using different blocks or have customised permission levels.

Development

This repository can be used directly with WordPress. For example, in your wp-content/plugins directory you can:

git clone git@github.com:Automattic/blocks-everywhere.git

You can then activate the plugin as normal and can follow the 'Building' instructions to build the files.

Sandboxes

If you wish to sync changes with a remote sandbox you add blocks_everywhere to your ~/.npmrc file. The value should point to the remote directory (including host and username). The directory should have a trailing slash.

For example blocks_everywhere=sandbox:public_html/wp-content/plugins/blocks-everywhere/.

Building

The JS and CSS needs to be compiled. You can do this in development mode, which will monitor for updates to the files:

yarn start

You can perform the same function but also upload to a remote sandbox (see sandbox configuration above):

yarn start:sync

If you want to build production files (minified and without debugging) then:

yarn build

And

yarn build:sync

Releasing

A release packages up all the JS, CSS, and PHP files into a clean directory without any development tooling.

yarn release

The plugin will be available in the release directory.

You can sync to a remote sandbox with (see sandbox configuration above):

yarn release:sync

Distribution

To produce a released and versioned distribution of the plugin run:

yarn dist

This will produce a zip file, upload it to Github, and mark it as an official release.

You can sync this to the WordPress.org SVN repo with:

yarn dist:svn

You will need appropriate permissions.

Documentation

For detailed technical documentation, see the /docs/ directory:

About

Use the Gutenberg block editor anywhere in WordPress.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages