Knowledge base — Definition
Gutenberg Editor
What the Gutenberg editor is, how its blocks are stored, how patterns and theme.json shape editing, and how custom blocks help content teams.
What Is the Gutenberg Editor?
The Gutenberg editor, officially called the block editor, is the default content editor in WordPress, in which every piece of content, whether a paragraph, image, heading, button or embedded form, is a separate block that can be added, moved, styled and reused.
It replaced the single text box of the classic editor when it shipped in WordPress 5.0 in December 2018. "Gutenberg" is also the name of the wider project, which has moved in phases: first the post editor, then site editing, where block themes let you edit headers, footers and templates in the Site Editor, followed by work on real-time collaboration and multilingual support. Development happens in the Gutenberg plugin first, and features are merged into WordPress core with each major release.
Why the Gutenberg Editor Matters
The block editor is now the foundation for how most WordPress sites are edited and themed.
- Visual editing in core: Editors can create multi-column layouts and rich pages without a third-party page builder.
- Portable content: Blocks are saved as ordinary HTML with comment markers, so content remains readable even if a block's plugin is removed.
- Design guardrails: Themes can restrict colours, font sizes and spacing to brand values, keeping pages consistent.
- Reusable building blocks: Patterns and synced patterns let teams insert pre-designed sections in a click.
- Developer extensibility: Custom blocks give editors purpose-built tools, replacing many shortcodes with something they can see and configure.
How the Block Editor Works
- Block markup: Each block is saved in post content wrapped in HTML comments, such as
<!-- wp:paragraph -->, with its settings stored as JSON in the opening comment. - Static and dynamic blocks: Static blocks save their final HTML; dynamic blocks, such as Latest Posts, save only their settings and are rendered by PHP on each request, so they stay current.
- theme.json: This file defines the colour palette, typography, spacing scale, layout widths and which controls editors can use, both in the editor and on the front end.
- Patterns: Pre-arranged groups of blocks. Synced patterns, formerly called reusable blocks, update everywhere they are used when edited once.
- Custom blocks: Built in JavaScript (React) with a
block.jsonmetadata file, often scaffolded with the@wordpress/create-blocktool, and registered by a plugin. - Templates and locking: Post types can have default block templates, and blocks can be locked so editors change content without breaking layout.
Common Gutenberg Editor Mistakes
- Leaving every option open: Giving editors unlimited colours, fonts and custom spacing, which leads to off-brand pages.
- Installing several block libraries: Adding multiple block collection plugins that overlap, load extra assets and complicate updates.
- Keeping the Classic Editor by default: Disabling blocks across the board rather than fixing the specific workflows that felt awkward, which leaves the site behind as WordPress evolves.
- Using Custom HTML blocks for layout: Hand-coded HTML in a block is hard for editors to change and easy to break.
- Ignoring heading structure: Picking heading levels for their size instead of their meaning, which hurts accessibility and SEO.
Best Practices for the Gutenberg Editor
- Define the design system in theme.json: Map your brand palette, type scale and spacing so editors choose from approved values.
- Build a pattern library: Create patterns for the sections your team uses most, such as hero, feature grid, testimonials and calls to action.
- Curate the block inserter: Hide blocks your site does not need so editors are not overwhelmed.
- Create custom blocks for repeated content: If a structure appears on many pages, a dedicated block with clear fields beats a fragile arrangement of core blocks.
- Train editors on the basics: List View, block navigation and patterns make the editor far easier once people know they exist.
The Gutenberg Editor at PerfectPixels
On our WordPress development projects, we set up theme.json around the client's brand, build pattern libraries and develop custom blocks for content that repeats, often tied to custom post types. The goal is an editor that feels like it was made for your team, with enough freedom to publish quickly and enough structure to stay on brand.
Frequently Asked Questions
Can I still use the classic editor?
Yes, the official Classic Editor plugin restores the old editing screen. It is a reasonable short-term option for specific workflows, but new WordPress features are built for blocks, so most sites benefit from moving to the block editor with sensible restrictions.
Do I need a block theme to use Gutenberg?
No. The block editor works for posts and pages with classic themes too. A block theme is only needed for full site editing, where headers, footers and templates are also edited with blocks in the Site Editor.
Is the block editor a replacement for page builders?
For many sites, yes. With a well-configured theme, patterns and a few custom blocks, it covers the layout needs that once required a builder, usually with lighter pages. Some teams still prefer a builder's interface for highly varied marketing pages.
Related Resources
Further reading: Block Editor Handbook — WordPress Developer Resources.