WordPress Gutenberg Block Editor — Complete Guide to Writing and Editing Content

In this tutorial, you'll learn to use the WordPress Gutenberg block editor — adding and arranging blocks, using block settings, writing in distraction-free mode, and mastering keyboard shortcuts for faster content creation.

What You'll Learn

• What Gutenberg is and why WordPress introduced it in version 5.0
• How the editor layout works: toolbar, content area, and sidebar
• How to add blocks using the plus button, slash command, and auto-complete
• How to move and arrange blocks with drag handles and keyboard shortcuts
• How to use the block toolbar and block settings panel
• How the Document tab controls post status, visibility, categories, and featured images
• How to use distraction-free mode, keyboard shortcuts, and block navigation
• How to revert to the Classic Editor if needed

Why It Matters

Before Gutenberg, WordPress used a simple text editor with a single content field — like writing a letter on a typewriter. You couldn't easily place an image next to text without knowing PHP or HTML. Gutenberg changed everything by making every piece of content a "block" you can move, style, and arrange visually. Understanding Gutenberg is essential because it now powers every WordPress site, and future WordPress features will build on it.

Real-World Use

A magazine website needs to mix text, pull quotes, image galleries, embedded videos, and call-to-action buttons within a single article. Before Gutenberg, this required custom shortcodes or HTML. Now you simply add a Paragraph block, then a Quote block, then a Gallery block — arrange them in any order — and publish. No coding required.

Learning Path

flowchart LR
    A[Posts vs Pages] --> B[Gutenberg Editor]
    B --> C[Core Blocks]
    B --> D[Block Patterns]
    C --> E[Writing Posts]
    D --> F[Publishing Workflow]
    E --> G[Managing Pages]

What is Gutenberg?

Gutenberg is the block-based editor introduced in WordPress 5.0 (released November 2018). Named after Johannes Gutenberg, inventor of the printing press, it replaced the old Classic Editor (TinyMCE) that had been WordPress's editing interface since 2003.

The key idea: everything is a block. A paragraph is a block. An image is a block. A button is a block. A YouTube embed is a block. Each block is independent — you can move it, style it, duplicate it, or delete it without affecting anything else.

Why Blocks?

Think of building with LEGO bricks. Each brick is a separate piece. You can take one brick off, replace it with a different color, or move it to a new position — and the other bricks stay exactly where they are. The Classic Editor was like writing on a single sheet of paper — everything was one piece. Gutenberg gives you LEGO bricks instead.

Editor Layout

The Gutenberg editor has three main areas:

The Toolbar (Top)

At the very top of the editor screen, you see:

• The WordPress logo — click to go back to the dashboard
• The editor title — click to rename your post
• Toolbar options — toggle between edit and select modes, undo/redo, show more tools
• Save Draft and Publish buttons
• Settings gear icon — opens/closes the sidebar

The Content Area (Center)

This is where you write. Each block appears as a separate rectangular area. Click inside any block to edit it. Click outside a block to see its outline and controls.

The Sidebar (Right)

The sidebar has two tabs:

• Document — controls for the entire post (status, categories, featured image, excerpt)
• Block — controls for the currently selected block (font size, color, alignment)

Adding Blocks

You have three ways to add a new block:

1. The Plus Button

Click the blue plus (+) button in the top-left corner of the editor. A block inserter panel opens showing all available blocks, organized by category: Text, Media, Design, Widgets, Theme, Embeds.

2. The Slash Command

Type / at the start of a new paragraph or inside an empty block. A menu appears listing blocks matching what you type:

/heading    → adds a Heading block
/image      → adds an Image block
/columns    → adds a Columns block
/button     → adds a Buttons block

3. Auto-Complete

Paste a YouTube or Twitter URL on its own line and Gutenberg automatically converts it to the correct embed block. Paste an image URL and it creates an Image block.

Moving and Arranging Blocks

Each block has a drag handle (six dots icon) on its left edge:

≡ Paragraph text goes here...

To move a block:

• Click and hold the drag handle, then drag up or down
• Or use the up/down arrow icons in the block toolbar
• Or use keyboard shortcuts: Option+Up/Down (Mac) or Alt+Up/Down (Windows)

Arranging Multiple Blocks

To select multiple blocks at once, click the three-dot menu in any block and choose "Select all blocks." You can then group them, move them together, or add them to a reusable block.

Block Toolbar

When you click inside a block, a block toolbar appears above it (or floats when the block is at the top of the screen):

[Transform] [B] [I] [Link] [More] [Move up] [Move down] [Options]

• Transform — change this block to a different type (paragraph to heading, list to quote)
• B/I — bold and italic text
• Link — add or remove a hyperlink
• More — additional formatting options (strikethrough, inline code, superscript, subscript)
• Move up/down — rearrange blocks
• Options — duplicate, insert before/after, edit as HTML, add to reusable blocks

Text Highlighting

Select any text within a block to see an inline toolbar with bold, italic, link, and inline code options — no need to use the main block toolbar.

Block Settings Panel

The Block tab in the right sidebar (gear icon) shows settings for the currently selected block. These settings vary by block type:

• Paragraph block: font size, drop cap, text color, background color, typography
• Image block: image size, alignment, alt text, link settings, border radius
• Heading block: heading level (H2, H3, H4), text alignment, color
• Button block: button text, link URL, color, border radius, width

Document Tab

The Document tab in the sidebar controls the overall post or page:

Why the Document Tab Matters

The Document tab is where you control how your content appears to the world, not just how it looks. Setting the right featured image and excerpt can double your click-through rate from social media and search results.

Distraction-Free Mode

Click the three-dot menu in the top-right corner and select "Distraction-free mode." This removes the toolbar, sidebar, and WordPress admin menu — leaving only your content.

To exit, click the "Exit distraction free" button that appears at the top of the screen.

Why use it? When you're writing, the visual noise of menus and settings panels can break your flow. Distraction-free mode is like turning off your phone notifications — you write faster and focus better.

Keyboard Shortcuts

Press Shift+Alt+H (or click the three-dot menu > Keyboard shortcuts) to see the full list. Here are the most useful ones:

Block Navigation and Outline

The block navigation icon (three horizontal lines with dots) in the top toolbar opens a tree view of all blocks in your post. This is especially useful for long posts with dozens of blocks:

Post Title
├── Paragraph: "In this tutorial..."
├── Heading: "What is Gutenberg"
├── Paragraph: "Gutenberg is..."
├── Image: gutenberg-editor-screenshot.png
└── Columns
    ├── Column
    │   ├── Heading: "Feature 1"
    │   └── Paragraph: "Description..."
    └── Column
        ├── Heading: "Feature 2"
        └── Paragraph: "Description..."

Click any item in the outline to jump directly to that block.

The List View

The List View panel (also called Block Navigator) lets you:

• Reorder blocks by dragging them in the tree
• Select blocks that are hard to click (like inside columns)
• See the structure of your content at a glance

Reverting to the Classic Editor

If you prefer the old editor or need to edit legacy content, install the Classic Editor plugin from the WordPress plugin Repository. It restores the TinyMCE editor and disables Gutenberg for all posts.

Alternatively, use the Classic block within Gutenberg — it embeds the old editor inside a single block. This is useful for pasting content from Microsoft Word or Google Docs that doesn't convert cleanly to blocks.

// You can also disable Gutenberg programmatically in functions.php:
add_filter('use_block_editor_for_post', '__return_false');

Common Mistakes

1. Adding blocks by pressing Enter repeatedly: Each press of Enter creates a new paragraph block. Instead, use / to choose the exact block type you need.

2. Not using the block settings panel: Many beginners edit only the content inside a block and miss the color, typography, and spacing options in the Block tab sidebar. Always check the sidebar for each block.

3. Forgetting to set the featured image: The featured image appears in search results, social media shares, and blog archives. A missing featured image makes your post look incomplete.

4. Copy-pasting from Word without cleaning: Pasting directly from Microsoft Word brings hidden formatting that creates messy HTML. Use the Classic block or paste into a plain text editor first.

5. Over-nesting blocks inside Groups and Columns: Wrapping blocks inside too many Group or Column blocks makes the content hard to edit and can break responsive layouts. Keep nesting to a maximum of three levels deep.

Practice Questions

1. What are the three ways to add a new block in Gutenberg?
2. How do you change a Paragraph block into a Heading block without deleting and re-adding it?
3. If you want to change the featured image of a post, which sidebar tab (Document or Block) do you use?

Challenge: Create a post with the following layout using only Gutenberg blocks: a two-column section with an image on the left and text on the right, followed by a quote, then a buttons row with two buttons side by side. Take a screenshot of the editor showing the block navigation outline.

FAQ

Mini Project

Write a complete blog post using the Gutenberg editor:

1. Add a title and a Paragraph block for the introduction
2. Insert a Heading block (H2) for the first section
3. Add an Image block with proper alt text
4. Insert a Quote block from a relevant source
5. Add a two-column Columns block with text in one column and a list in the other
6. Add a Buttons block with a "Learn More" link
7. Set a featured image, choose a category, and add three tags in the Document sidebar
8. Preview the post and verify everything looks correct
9. Save as Draft

What's Next

Now that you know the editor, explore the Core Blocks reference to learn every built-in block and when to use it. Then learn Block Patterns and Reusable Blocks to speed up your content creation.

For more on the writing Process, see Writing Posts and Managing Pages.