Docs Block Developer Guide

Building a New Block — Upload and Install

Once all five files are ready:

  1. Zip the block folder. The block folder itself must be the root of the ZIP — not a parent folder containing it.

– ✅ feature-card.zip → block.json at root – ❌ feature-card.zip → feature-card/ → block.json

  1. Go to Custom Blocks → Blocks tab in the admin.
  1. Drag and drop the ZIP or click to upload. wpTruss extracts the files, then immediately runs the Block Validator against all 12 governance rules. If any rule fails, the block is not registered and the validator outputs the file name, line number, violation found, and the correct fix. Resolve each violation and re-upload.
  1. Go to Custom Blocks → Block Audit tab. Find your block in the table. Click Re-register to sync it with the current Panel Registry definitions. Do this immediately after every upload, and again any time the Panel Registry is updated.
  1. Open any post or page in the editor. Your block appears in the wpTruss block category. Insert it, open the inspector, and verify all five panels render with the correct option sets from the registry.