WordPress VIP Block Governance plugin

This WordPress plugin adds additional governance capabilities to the block editor. This is accomplished via two dimensions:

Insertion: restricts what kind of blocks can be inserted into the block editor. Only what’s allowed can be inserted, and nothing else. This means that even if new core blocks are introduced they would not be permitted.
Interaction: This adds the ability to control the styling available for blocks at any level.

We have approached this plugin from an opt-in standpoint. In other words, enabling this plugin without any rules will severely limit the editing experience. The goal is to create a stable editor with new blocks and features being enabled explicitly via rules, rather than implicitly via updates.

This plugin is currently developed for use on WordPress sites hosted on the VIP Platform.

Try it out
Installation
- Install on WordPress VIP
- Install via ZIP file
Usage
Code Filters
Admin Settings
Endpoints
- vip-governance/v1/<role>/rules
  - Example
Analytics
Development
- Tests

Try it out

Try out the VIP Governance plugin in your browser with WordPress Playground.

Installation

To use the WordPress VIP Block Governance plugin after activation, skip to Usage.

Install on WordPress VIP

The WordPress VIP Block Governance plugin is authored and maintained by WordPress VIP, and made available to all WordPress sites by VIP MU plugins. Customers who host on WordPress VIP or use vip dev-env to develop locally have access to this plugin automatically. We recommend this activation method for WordPress VIP customers.

Enable the plugin by adding the method shown below to your application's [client-mu-plugins/plugin-loader.php][vip-go-skeleton-plugin-loader-example]:

// client-mu-plugins/plugin-loader.php

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

Create this path in your WordPress VIP site if it does not yet exist.

This will automatically install and activate the latest mu-plugins release of the WordPress VIP Block Governance plugin. Remove this line to deactivate the plugin.

Install via ZIP file

The latest version of the plugin can be downloaded from the repository's Releases page. Unzip the downloaded plugin and add it to the plugins/ directory of your site's GitHub repository.

Usage

Your governance rules are saved in governance-rules.json in your private folder. Before diving into how it's used, a quick run down of the schema will shed light on how it works.

Note: The private folder is only supported on VIP sites, or while using vip dev-env locally.

Schema Basics

You can find the schema definition used for the rules here. You can use https://api.wpvip.com/schemas/plugins/governance.json as the schema entry in your rules, to take advantage of code completion in most editors.

We have allowed significant space for customization. This means it is also possible to create unintended rule interactions. We recommend making rule changes one or two at a time to troubleshoot these interactions.

Each rule is an object in an array. The one required property is type, which can be default, role, or postType. Your rules should only have one entry of the default type, as described below, and it is the only type that is required in your rule set.

Rules not of type default require an additional field. These are broken down below, along with examples of their possible values:

Rule Type	Required Field	Possible Values
`role`	`roles`	name/slug of any default or custom roles
`postType`	`postTypes`	name/slug of any default or custom post types

Each rule can have any one of the following properties.

allowedFeatures: This is an array of the features that are allowed in the block editor. This list will expand with time, but we currently support two values: codeEditor (viewing the content of your post as code in the editor) and lockBlocks(ability to lock/unlock blocks that will restrict movement/deletion). If you do not want to enable these features, omit them from the array.
blockSettings: These are specific settings related to the styling available for a block. They match the settings available in theme.json under the key blocks. The definition for that can be found here. Unlike theme.json, you can nest these rules under a block name to apply different settings depending on the parent of a particular block.
allowedBlocks: These are the blocks allowed to be inserted into the block editor. Additionally, you can use allowedBlocks in blockSettings rules to restrict what blocks can be nested under a parent.

Non-default rule types will be merged with the default rule. This is done intentionally to avoid needless repetition of your default properties. If multiple non-default rule types are provided, they will be applied in the following ascending priority:

Post Type
Role

So if a matching postType and role rule is found, the role rule will be applied, and the postType rule will be ignored. The best analogy is the CSS cascade where more specific rules overwrite less specific rules. We are making a choice that Role-based rules should overwrite Post Type rules. We will introduce a filter in the near future to allow this priority to be customized.

Wildcards

The wildcard * can be used within allowedBlocks and within blockSettings to target more than 1 block. The intention is that it will limit repeated rules, and allow greater flexibility in controlling the editor experience.

For an example of this feature, refer to the example file here.

Note: allowedBlocks are not respected when a parent blockSettings also has a wildcard. For example, this will not work:

❌ Using `allowedBlocks` under a parent wildcard:

{
  "$schema": "https://api.wpvip.com/schemas/plugins/governance.json",
  "version": "1.0.0",
  "rules": [
    {
      "type": "default",
      "allowedFeatures": [ "codeEditor", "lockBlocks" ],
      "allowedBlocks": [ "core/*" ],
      "blockSettings": {
        "core/*": {
          "allowedBlocks": [ "core/paragraph", "core/heading" ],  // ← Not allowed under "core/*"
          "color": {
            "text": true,
          }
        }
      }
    }
  ]
}

Instead, only apply block settings to wildcards, and specify allowedBlocks to individual parent blocks:

✅ Using `allowedBlocks` under defined blocks:

{
  "$schema": "https://api.wpvip.com/schemas/plugins/governance.json",
  "version": "1.0.0",
  "rules": [
    {
      "type": "default",
      "allowedFeatures": [ "codeEditor", "lockBlocks" ],
      "allowedBlocks": [ "core/*" ],
      "blockSettings": {
        "core/*": {
          "color": {
            "text": true
          }
        },
        "core/quote": {
          "allowedBlocks": [ "core/paragraph", "core/heading" ]
        },
        "core/media-text": {
          "allowedBlocks": [ "core/paragraph", "core/heading" ]
        }
      }
    }
  ]
}

Quick Start

By default, the plugin uses this governance-rules.json. To start using the plugin with your own rules, you'll need to create your own governance-rules.json in your private folder. We recommend duplicating one of the starter rule sets provided below, and adapting it for your needs. In order to take advantage of the rules schema for in-editor support, use https://api.wpvip.com/schemas/plugins/governance.json.

With this default rule set, all blocks and all features are enabled. It is sensible to set your default rule to the settings you want for your least privileged user then add capabilities with role and/or post type-specific rules.

Starter Rule Sets

Below is some rule sets that you can use to build your governance-rules.json. They cover a wide range of use cases.