Before you build a custom block, you need to understand what Gutenberg actually is. Most “build a block” tutorials skip this and jump straight to React. That gap is why so many block plugins are written incorrectly and break in production. This tutorial covers the architecture so the rest of the series makes sense.

What is Gutenberg?

Gutenberg is the codename for WordPress’s block editor, introduced in WordPress 5.0 (December 2018) and now the default editing experience. The name comes from Johannes Gutenberg, inventor of the printing press — a reference to how the editor was meant to reinvent web publishing.

Three key facts:

1. Gutenberg is a React app embedded in wp-admin. When you load a post-edit screen, WordPress serves the standard admin HTML chrome and mounts a React application inside it. The React app handles every interaction with content.
2. The block editor is one part of a larger Gutenberg project. The other parts: full-site editing (FSE), the navigation editor, the styles UI, and patterns. They all share the same underlying block model.
3. “Everything is a block” is literal. A paragraph, a heading, an image, a navigation menu, a footer — all blocks. Even classic post content is wrapped in a “Classic” block on the way in.

The architectural shift

Pre-Gutenberg, post content was a single post_content field — a giant string of HTML and shortcodes saved to the database. The editor was TinyMCE plus a “Text” tab. To customize an element you wrote a shortcode ([my_callout]) and let users guess at attributes.

Gutenberg replaces that string with a parsed tree of blocks. Each block has:

• A type (e.g., core/paragraph, core/image, my-plugin/callout)
• Attributes (text content, color, alignment, custom props)
• An HTML representation with HTML comments as delimiters

When you save a post, WordPress serializes the block tree to HTML annotated with comments. On load, it parses those comments back into block instances. The post_content table column still stores a string, but that string is now machine-readable.

A simple paragraph block serializes like this:

<!-- wp:paragraph -->
<p>Hello, world.</p>
<!-- /wp:paragraph -->

A custom block carries attributes in the opening comment:

<!-- wp:my-plugin/callout {"type":"warning","title":"Heads up"} -->
<div class="wp-block-my-plugin-callout">...</div>
<!-- /wp:my-plugin/callout -->

This is the fundamental change. Content is now structured data, not free-form HTML.

Block lifecycle

A block has two render phases that you, the plugin author, control:

1. Edit — the React component shown in the editor when someone is authoring. Has access to attributes, can render controls, accepts user input.
2. Save — the serialized HTML output stored in post_content and rendered on the front-end. Can be static (computed at save time) or dynamic (rendered server-side via PHP on each request).

What you don’t need to know yet

Three things often confuse newcomers but don’t matter at the architecture level:

• JSX vs createElement — JSX is just syntactic sugar over React.createElement(). WordPress’s build tool (@wordpress/scripts) handles the transform; we’ll use JSX in this series.
• wp.element vs react — WordPress wraps React in @wordpress/element. They’re functionally interchangeable for our purposes. Use wp.element to match the WordPress idiom.
• The interactivity API — a newer, optional layer for adding client-side state to dynamic blocks without shipping React to the front-end. Worth knowing exists; we’ll cover it in Part 9.

Why blocks matter beyond the editor

The block model isn’t just an editing UX improvement. It enables:

• Block patterns — pre-designed combinations of blocks users can drop in (covered in Part 8)
• Full-site editing — themes assembled from blocks instead of PHP templates
• AI integration — structured content is easier for LLMs to read and modify
• Cross-platform parity — the same block tree can render in mobile apps, headless front-ends, and the wp-admin editor

If you’re going to build for modern WordPress, blocks are the surface.

What’s next

You now know what Gutenberg is and how blocks are stored. In Part 2, we set up your development environment — Node.js, the @wordpress/create-block scaffold, and a local WordPress install ready to develop against.