Shortcode to Block Example

Many institutions can’t migrate to the WordPress block editor all at once, and they don’t have to. Large sites often rely on legacy shortcodes that are deeply embedded across hundreds of pages, and depending on the timeline and budget of the project, a full rewrite of the site is not always an option, and often unnecessary.

This repository demonstrates a practical, low-risk approach to modernization by converting an existing shortcode into a server-rendered block. Instead of replacing working logic, the block reuses the existing PHP rendering function and layers an intuitive editing interface on top of it.

The goals of this example are to:

• Reuse existing rendering logic to avoid duplication
• Introduce block controls that enhance the editor user experience
• Use block editor filters to remove block controls based on user roles
• Provide a modern architecture for creating block plugins

Following this pattern can enable teams to progressively improve the editing experience while preserving current frontend output; allowing for an incremental, intentional, and safe adoption of the block editor.

Project Structure

Below is the main plugin file structure. The rest of the files in the project root folder are configuration files, and package manager files for NPM and Composer.

shortcode-to-block/
├── .bin/                    # create-block script & templates
├── inc/                     # PHP files loaded in main file
├── src/                     # Source files
│   └── blocks/              # Block source files
├── README.md                # Project README file
└── shortcode-to-block.php   # Main plugin file

The create-block script will create a block within the scr/blocks folder with the following structure.

my-custom-block/
├── block.json    # Defines metadata, attributes, and file locations
├── edit.js       # Defines how the block behaves in the editor
├── editor.scss   # Editor-only styles
├── index.js      # Main block file, registers the block in JS
├── render.php    # Handles server-side rendering logic
├── style.scss    # Editor and front-end styles
└── view.js       # Handles front-end JS functionality

Development

This plugin includes modern development tools configured in package.json and composer.json.

Getting Started

1. Install the plugin manually or through git clone git@github.com:humanmade/shortcode-to-block.git.
2. Navigate to the plugin folder cd shortcode-to-block.
3. Run composer install.
4. Run npm install.
   • Note: If you are using nvm for managing Node versions, run nvm use to switch to the recommended version, otherwise use v22 to avoid any incompatibility issues.
5. Run npm run build to generate the static build files.

Available Commands

• npm run dev: Run the development server.
• npm run build: Run a static build.
• npm run create-block <block-name>: Scaffold a server-rendered block.
• npm run format:js: Autoformat first-party JS code in the plugin.
• npm run format:php: Autoformat first-party PHP code in the plugin.
• npm run lint:js: Report on code issues in first-party JS files.
• npm run lint:php: Report on code issues in first-party PHP files.
• npm run lint: Report on code issues in first-party JS and PHP files.

Process Overview

1. Start by creating the basic structure of a server-rendered block: npm run create-block <block-name>.
2. Determine all the shortcode attributes you will be using.
3. Register a block attribute in block.json for each of the shortcode attributes.
4. Create the editor UI by leveraging WordPress block editor components.
5. In the edit.js function, use the ServerSideRender component for displaying the shortcode output in the editor.
6. In the render.php file use do_shortcode() to call the same legacy rendering function from the shortcode.

Useful Links

• Block Editor Handbook: Global Settings & Styles (theme.json)
• Theme.json Version 3 Reference
• 15 ways to curate the WordPress editing experience