Wicked Evolutions Knowledge Docs

v0.3.0

Pages
Getting Started
Products
Core Concepts
For AI Agents
Policy
Reference Library

Docs ›

Parse, find, insert, update, and remove individual Gutenberg blocks within post content. Surgical editing without touching the full post.

, , , ,

13

Total Abilities

7

Read

5

Write

1

Delete

Overview

The Blocks module provides surgical access to individual Gutenberg blocks within a post’s content. Instead of reading, modifying, and rewriting the entire post_content, you can parse the block tree, locate specific blocks by type or attribute, update their properties, insert new blocks at specific positions, or remove blocks — all without touching the surrounding content.

This module works alongside the Content module. Content gives you post-level CRUD; Blocks gives you block-level precision within a post.

Ability Reference

AbilityTypeDescription
blocks/parseRParse a post’s content into a block array. Returns block name, attributes, innerHTML, and innerBlocks.
blocks/find-in-postRFind blocks in a post by block name, className, or attribute value. Returns matching blocks with their paths.
blocks/find-nestedRSearch for blocks within nested innerBlocks structures. Deep recursive search.
blocks/get-at-pathRGet a specific block by its path in the block tree (e.g., [2, 0, 1]).
blocks/get-typeRGet the registered block type definition — attributes schema, supports, category.
blocks/list-typesRList all registered block types on the site.
blocks/serializeRConvert a block array back into HTML block markup ready for content/update.
blocks/insertWInsert a new block at a specific position in a post’s block tree.
blocks/update-attributesWUpdate attributes on a block found by path. Merges with existing attributes.
blocks/update-at-pathWReplace an entire block at a specific path in the tree.
blocks/replaceWReplace a block matching search criteria with new block markup.
blocks/append-innerWAppend a block as a child of an existing block’s innerBlocks.
blocks/removeDRemove a block at a specific path from a post’s block tree.

Common Workflows

Find and update a specific block

1. blocks/find-in-post       → search by blockName or className
2. blocks/get-at-path        → verify the block at the found path
3. blocks/update-attributes  → merge new attributes
   ⚠️ Do NOT use on text-containing blocks — destroys innerHTML

Add a section to an existing page

1. content/append            → append block markup (no read needed)
   OR
1. blocks/parse              → get current block tree
2. blocks/insert             → insert at specific position
   Note: content/append is simpler when adding to the end

Known Gotchas

blocks/update-attributes destroys innerHTML. When used on text-containing blocks (paragraphs, headings, lists), the innerHTML is lost. The block saves with correct attributes but empty text. Use only on wrapper Groups or structural blocks with no text content. Recovery: revisions/restore.

blocks/insert loses innerBlocks on nested structures. When inserting a block that contains innerBlocks, the inner structure may not be preserved by serialize_block(). Prefer content/append with pre-serialized block markup for complex nested content.

Path indexing is zero-based. Block paths like [2, 0, 1] mean: third top-level block → first innerBlock → second innerBlock. Off-by-one errors are common. Always verify with blocks/get-at-path before modifying.

Content Module

17 abilities — post-level CRUD

Revisions Module

5 abilities — recovery from block damage

Related