WordPress VIP Block Governance plugin

The WordPress VIP Block Governance plugin provides the ability to limit the types of Gutenberg blocks that can be added to the block editor and the styles that can be applied to them. The rules applied for block and style options can also be defined by specific post types and/or user roles.

Applying block and style rules with the WordPress VIP Block Governance plugin enables the rules of a design system to be encoded into a site’s block editor, and for the complexities of content creation to be reduced for editors.

The WordPress VIP Block Governance plugin is authored and maintained by WordPress VIP, and made available to all WordPress sites by VIP MU plugins.

Limitation

For WordPress multisite environments, governance rules added to the WordPress VIP Block Governance configuration file cannot be defined per-network site.

Enable the WordPress VIP Block Governance plugin

The WordPress VIP Block Governance plugin can be code-enabled for a VIP Platform WordPress site by adding the method shown below to an application’s plugin-loader.php. If a plugin-loader.php does not yet exist, create the file in the application’s client-mu-plugins directory.

\Automattic\VIP\Integrations\activate( 'vip-governance' );

Configuration file

Custom rules for access governance (e.g., styles, block types, the code editor, user roles, post types) are added to a governance-rules.json configuration file.

Custom rules defined in governance-rules.json can:

• Apply restrictions to the types of blocks that can be inserted into the block editor.
• Apply restrictions to the styling options that can be configured for blocks at any level.
• Apply restrictions to the block options and/or styling options that will be available based on WordPress core or custom user roles.
• Apply restrictions to the block options and/or styling options that will be available based on WordPress post types.

Refer to the WordPress VIP block Governance plugin’s GitHub repository for detailed instructions on configuring governance-rules.json. Review the “Schema Basics” section to gain an understanding of how rules are added and applied.

Structure and location

Create a governance-rules.json configuration file and add it to the /private directory of an application’s wpcomvip GitHub repository. It is recommended to use this example rule set in the configuration file as a starting point:

{
  "$schema": "https://api.wpvip.com/schemas/plugins/governance.json",
  "version": "1.0.0",
  "rules": [
    {
      "type": "default",
      "allowedFeatures": [ "codeEditor", "lockBlocks" ],
      "allowedBlocks": [ "*" ]
    }
  ]
}

Review the “Starter Rule Sets” section in the WordPress VIP Block Governance plugin’s GitHub repository for several different configuration code examples.

Avoid disallowing the  core/paragraph block

When adding custom rule sets to the configuration file, avoid rules that disallow the usage of the core/paragraph block. The core/paragraph block is used by the block editor as an insertion primitive. If usage of the core/paragraph block is disallowed for a user:

• The user will be unable to populate allowed blocks by typing prompts in the content editor (e.g. /header). The user will instead be required to add allowed blocks by selecting them from the Block Inserter.
• The inclusion of the core/paragraph block will not be prevented where it is automatically nested within another block (e.g. core/quote).

WordPress Admin dashboard settings

A settings page in the WordPress Admin dashboard for the WordPress VIP Block Governance plugin provides features for enablement and debugging.

Access the plugin’s settings page is limited to user roles with the manage_options capability (e.g., Administrators on WordPress single sites and Super Admins on WordPress multisites).

Select the lefthand navigation menu item labeled “VIP Block Governance” to access the settings page in the WordPress Admin dashboard.

• Plugin Settings: The rules applied by the plugin can be disabled and re-enabled within the settings panel. This eliminates the need to modify and deploy code in a situation that requires the plugin’s functionality to be quickly disabled.
• Governance Rules Validation: A validation tool scans the custom configurations added to governance-rules.json and reports the type and location of any errors identified in the JSON ruleset.
• View Governance Rules For A Rule Type: The settings added to governance-rules.json can be filtered and viewed by a combination of role type and post type. If multiple rules exist for the requested filter combination, they will be compiled in the displayed output.