Block Editor for Authors

The block editor (also called the WordPress editor, or Gutenberg after the project that builds it) became the default editor in WordPress 5.0 in December 2018, replacing the TinyMCE-based "classic" editor. Every piece of content is a block: a paragraph, a heading, an image, a list, a group of other blocks. Each block has its own toolbar, its own settings in a sidebar, and its own markup.

Internally the editor is a JavaScript (React) application that runs in the browser. It loads the post through the REST API, keeps the blocks in memory as a tree of objects (name, attributes, inner blocks), and saves them back as HTML with special HTML comments, called block delimiters, around each block. That text is stored in the post_content column of the wp_posts table (see Database Schema). When the editor opens the post again it parses the delimiters back into blocks; when a visitor views the post, PHP parses the same text and renders each block. Plugins and themes add their own blocks to the same system.

Since WordPress 7.1 the editing canvas (the area where the blocks are shown) always runs inside an iframe, as the Site Editor already did. The theme’s editor styles apply only to the content, not to the admin interface around it. In 7.0 the iframe was used only when every block in the post used block API version 3; in 7.1 it is enforced for all posts, including those with legacy meta boxes. For authors this mostly means the canvas looks more like the front end; for developers it means plugin code that reaches into the admin page’s document from inside the canvas breaks (see block.json and Registration).

Real-time collaborative editing (several people typing in the same post at once) did not ship. It was removed from 7.0 shortly before release, was not part of 7.1, and has no release scheduled. When two people open the same post, WordPress still uses post locking: the second person is told who is editing and can go back, preview or take over. The collaboration features that do exist are Notes (6.9, extended in 7.1) and revisions, both covered below.

The examples on this page create content with WP-CLI against a disposable site. The following Compose file starts WordPress 7.1.3 with MariaDB 11.8 and adds a WP-CLI 2.12.0 service that shares the WordPress files. The content directory next to it holds the block markup files used below and is mounted read-only into the WP-CLI container.

Source: Docker Hub: wordpress (official image)

Start the site, install it and create two of the Lumen Press users: an editor and an author. The wp alias below is only a shorthand for the long docker compose run command; the database password comes from the environment and is never written into a file.

Source: WP-CLI Commands: wp core install

If wp reports that wp-config.php is missing, wait a few seconds: the WordPress container copies its files into the volume on first start. wp core install prints a generated administrator password when --admin_password is omitted; store it in a password manager. The two wp user create commands print the new user IDs, 2 for maria.editor and 3 for tom.author, which the later commands use. docker compose --profile tools down -v removes everything, volumes included.

The figure is a schematic of the post editor while Tom, an author, writes the announcement of a new Lumen Noir title. It is a simplified drawing, not a screenshot; the real icons differ.

The editor opens in fullscreen mode (the admin menu is hidden) by default since WordPress 5.4. Its three permanent areas are the top toolbar, the content canvas and the settings sidebar; the Document Overview panel opens on demand on the left.

There are several ways to add a block, and authors who write long texts usually settle on the keyboard ones:

Two text shortcuts work inside any rich-text block: typing [[ opens a search of existing posts and pages to link to, and selecting text and pressing the backtick key turns it into inline code.

The block directory extends the inserter search: when no installed block matches, the inserter searches the single-block plugins on WordPress.org and offers to install one. This is only shown to users with the install_plugins capability (administrators on a single site), and it installs and activates a whole plugin, so the plugin vetting rules of Choosing and Managing Plugins and Themes apply. Sites that set DISALLOW_FILE_MODS do not show it.

Source: WordPress.org Documentation: Adding a new block

Shift+Alt+H (Ctrl+Option+H on macOS) opens the list of shortcuts inside the editor. The most useful ones:

Source: WordPress.org Documentation: Use keyboard shortcuts (Block Editor)

Ctrl+K has two meanings: with text selected inside a block it creates a link; elsewhere it opens the Command Palette. Some shortcuts collide with browser or desktop shortcuts (Ctrl+Alt+T opens a terminal on several Linux desktops); the list inside the editor is authoritative for the installed version.

The Code editor shows what the editor actually stores. Each block is wrapped in an opening and a closing delimiter, <!-- wp:paragraph --> and <!-- /wp:paragraph -->. The block name follows wp: (core blocks drop the core/ prefix; a plugin block is written with its namespace, as in <!-- wp:lumen/book-card -->). Attributes that are not derived from the HTML are stored as a JSON object inside the opening delimiter. Blocks without saved HTML, such as dynamic blocks rendered by PHP, use a self-closing delimiter like <!-- wp:post-time-to-read /-->. Nested blocks appear inside their parent’s markup.

The following file, content/lighthouse-ledger.html in the sandbox, is the announcement post of The Lighthouse Ledger, the first title of the Lumen Noir imprint. It contains text blocks, a quote with a nested paragraph, a list, an accordion with a frequently asked question, a paragraph hidden on mobile and a button:

Source: Block Editor Handbook: Markup representation of a block

The markup was checked with the block parser and validator of @wordpress/blocks 15.27.0 and @wordpress/block-library 10.2.0 from npm (WordPress 7.1.3 itself bundles @wordpress/blocks 15.24.0, from its Gutenberg build): all 16 blocks parse as valid.

That validation is what decides whether the editor accepts hand-written or migrated markup. For a static block (one whose HTML is produced by a JavaScript save function), the editor regenerates the HTML from the parsed attributes and compares it with what is stored. If they differ and no deprecated version of the block matches, the block shows "Block contains unexpected or invalid content." with Attempt recovery, and the More options menu offers Resolve Block, Convert to blocks or Keep as HTML. Changing classes or structure by hand, or copying markup between WordPress versions, is the usual cause; dynamic blocks are not validated because their HTML is produced on the server. The front end is not affected: PHP renders whatever is stored.

Content without delimiters, such as a post written in the classic editor, is opened as one Classic block (the core/freeform block). Its More options menu has Convert to blocks, which splits it into paragraphs, headings and lists.

Because a post is just text with delimiters, any tool that writes post_content can create block content: an import script, the REST API, or WP-CLI. wp post create takes the content from a file:

Source: WP-CLI Commands: wp post create

--post_author takes a user ID; a login name such as tom.author is silently stored as author 0. --post_category accepts names or IDs of existing categories. The file is stored as it is: WP-CLI does not run the editor’s block validation, so markup that is not what the blocks would save shows the validation error described above the first time someone opens the post in the editor. Validating imported markup before a bulk import avoids that.

parse_blocks() is the PHP side of the same grammar. Listing the top-level blocks of the new post shows the names, the JSON attributes from the delimiters and the number of nested blocks:

Source: Code Reference: parse_blocks()

The blank lines between blocks are parsed as blocks with a null name (freeform whitespace), which is why the loop skips entries without a blockName. serialize_blocks() turns the array back into markup, which is how the Notes example below edits a block attribute.

WordPress 6.9 added Hide to the block menu, and 7.0 extended it to individual screen sizes. Both are set from the More options menu, the List View menu, the Command Palette or Ctrl+Shift+H, which open the block visibility dialog:

The rendered Lumen Press post shows the difference. The paragraph hidden on mobile keeps its text and gets a class, and the block-support stylesheet adds the matching media query; a paragraph omitted from published content renders as an empty string:

Source: Make WordPress Core: Block visibility in WordPress 7.0

The breakpoints come from the theme. With the default values they are mobile up to 480 px, tablet from 481 to 782 px and desktop above 782 px; since 7.1 a block theme can change them with settings.viewport in theme.json, and the same breakpoints drive the 7.1 responsive styles (see theme.json Settings).

Viewport hiding is a layout tool, not a privacy tool. Hidden content is still sent to every visitor, is visible in the page source and can be indexed by search engines; embargoed text, prices that must not leak or personal data must be omitted (or kept in a draft), not hidden by viewport. Keeping separate "desktop" and "mobile" copies of the same text also duplicates it for search engines; a responsive layout is usually the better answer. Blocks whose type declares "visibility": false in its supports do not offer the control, but a block saved with blockVisibility: false is never rendered, whatever its support says.

A pattern is a ready-made group of blocks inserted from the Patterns tab of the inserter. Authors meet three kinds:

User patterns are posts of type wp_block. Unsynced ones carry the meta key wp_pattern_sync_status with the value unsynced; synced ones have no such key. The Lumen Press "buy at your local bookshop" message, saved as content/bookshop-cta.html, as both kinds:

Source: WordPress.org Documentation: Patterns

Creating, categorising, exporting and overriding patterns is covered in Patterns for Site Builders; registering patterns in a theme is covered in Theme Patterns.

Notes, added in WordPress 6.9, let people who can edit a post leave feedback on it without changing the content. WordPress 7.1 extended them considerably. Notes never appear on the front end.

Source: WordPress.org Documentation: Notes

Notes follow the post’s edit permission: administrators and editors can see and add notes on all posts, authors and contributors only on their own posts, subscribers not at all. They are available in the post and page editors (and in custom post types that enable them), but not in the Site Editor for templates and template parts. There is no "notes assigned to me" view. Before WordPress 7.1.4 (a security release of 2026-10-28), privileged users who could not edit a post could still read the notes attached to it; 7.1.4 enforces the rule above, so a site where notes discuss unpublished material should run it (WordPress News: WordPress 7.1.4).

Internally a note is a comment with comment_type note. An open note has comment_approved 0, a resolved one 1, and a deleted one goes to the trash. Replies are child comments. The block points to its top-level note with noteId in its metadata attribute; the note does not store which block it belongs to. Notes are excluded from normal comment queries, so code must ask for type note explicitly; the REST API exposes them at /wp/v2/comments?post=<id>&type=note to users who can edit the post.

The following commands reproduce, with WP-CLI, what Maria (editor) and Tom (author) do in the editor: Maria leaves a note, Tom replies, the note is attached to the first paragraph, and Maria resolves it.

Source: Make WordPress Core: Notes Feature in WordPress 6.9

The plain wp comment list count is 0: notes are not comments for any code that does not ask for them. The next script attaches note 2 to the first block by editing the parsed block array and serializing it back, exactly the attribute the editor writes:

Source: Code Reference: serialize_blocks()

Approving the comment is what Resolve does. Here only the top-level note changes status; the reply stays at 0.

Notes are on for posts and pages. A custom post type such as the catalogue’s lp_book enables them with 'supports' => array( 'title', 'editor' => array( 'notes' => true ) ) in register_post_type(), the same value core uses for posts; the type also needs show_in_rest, or it does not use the block editor at all. Because add_post_type_support() replaces the editor sub-features instead of merging them, a plugin that adds Notes to a post type registered elsewhere must merge the existing editor features first; the Notes developer note shows both, and Custom Post Types and Taxonomies covers registration.

Every save of a post creates a revision (a copy of the title, content and excerpt), and the editor keeps one autosave per user per post. The Revisions panel of the Post tab shows how many there are; clicking it opens the revisions screen.

WordPress 7.0 replaced the old side-by-side HTML diff with a visual revisions screen inside the editor:

The classic screen is still available through Open classic revisions screen; it is the one with Compare any two revisions. Revisions are stored as wp_posts rows of type revision, children of the post, named <post-id>-revision-v1; the Lumen Press draft above has one, 4-revision-v1, created when the note was attached.

Source: WordPress.org Documentation: Revisions

The limit (WP_POST_REVISIONS, the wp_revisions_to_keep filter) and autosave timing are covered in Posts and Pages. Revisions record the title, content and excerpt; terms are not revisioned, and post meta only when it is registered with revisions_enabled (6.4 and later), so a restore does not bring back an earlier category or, usually, an earlier featured image.

WordPress 7.1 registers 116 block types. Many are only for templates (theme blocks) or are children of other blocks; the inserter groups the rest into Text, Media, Design, Widgets, Theme and Embeds. The blocks an author uses most, and the ones added recently:

Source: WordPress.org Documentation: Blocks list

Several blocks lost the word "Post" from their titles in 6.9 (Title, Excerpt, Featured Image, Author Name, Tags); the markup names, such as post-title, did not change. The old Post Author block was deprecated in 7.0: it is hidden from the inserter but existing instances still render. Plugins add their own blocks next to these; the Lumen Press catalogue blocks (lumen/book-card, lumen/latest-books, lumen/wishlist) are built in the Block Development pages starting at Block Development Environment.

The second Lumen Press post uses two of the newer blocks, Tabs with the synopsis and reviews and a Math formula with the reading-time estimate used by Time to Read, plus an embed of another WordPress site. It is saved as content/tour.html.

Source: Block Editor Handbook: Core Blocks Reference

The nine blocks of this file pass the same editor validation as the first post; the next section creates it as post 8. On the front end the Tabs block is rendered with Interactivity API directives (the tab buttons get aria-controls and aria-selected bindings), the Math block outputs the stored MathML, and the embed becomes the provider’s HTML, cached as shown in the next section. In JSON attributes the editor escapes backslashes as \u005c, which is why the LaTeX attribute looks different from the annotation in the HTML.

Content from video, audio, social and document services is embedded, not uploaded: the post stores only the URL, and WordPress asks the service for the HTML to show. Authors either use the generic Embed block or a provider variation (YouTube, Vimeo, Spotify, SoundCloud, Bluesky, X, TikTok, WordPress and others), or simply paste the URL on its own empty line, which the editor turns into the right embed block. If the provider is not supported, or the URL is private, the block shows "Sorry, this content could not be embedded." with Try again and Convert to link.

The mechanism is oEmbed. Core keeps an allowlist of providers and their oEmbed endpoints; for those, any user who can edit posts can embed. For other sites WordPress uses oEmbed discovery (the <link type="application/json+oembed"> tag in the page head) since 4.4, but filters the result heavily: only links, blockquotes and sandboxed iframes survive. Users with the unfiltered_html capability (administrators and editors on a single site) bypass part of that filtering, which is one more reason to give that capability only to trusted people. Facebook and Instagram embeds stopped working in October 2020, when Meta closed its unauthenticated endpoint; core removed those providers in 5.6, and those URLs now need a plugin with Meta app credentials.

The response is cached in post meta (_oembed_<hash> and _oembed_time_<hash>), so the provider is not called on every page view. WP-CLI creates the tour post of the previous section, shows which endpoint its embed URL resolves to, renders the post once and lists what was cached:

Source: WP-CLI Commands: wp embed provider match

Embedding another WordPress site, as here, works by discovery because every WordPress site is an oEmbed provider (/wp-json/oembed/1.0/embed); the result is a sandboxed iframe with a blockquote fallback. Third-party embeds load scripts and cookies from the provider when the page is viewed, which has privacy consequences covered in SEO, Analytics and Privacy. Developers add providers with wp_oembed_add_provider() (see Advanced Administration Handbook: oEmbed).

Sites that cannot move to blocks yet (custom meta boxes that were never ported, editorial habits, third-party plugins built for the old screen) can install the official Classic Editor plugin, maintained by WordPress contributors. It restores the TinyMCE editor and the old Edit Post screen. Its page promised full support "until 2024, or as long as is necessary"; version 1.7.0, tested up to WordPress 7.0.7, was the current one on 2026-10-28.

WordPress core itself has no setting to choose the editor. The choice appears under Settings > Writing only while the plugin is active: Default editor for all users (Classic or Block editor) and Allow users to switch editors. With switching allowed, each user picks a default on their profile, and the Posts list shows links to open a post in either editor. On Multisite the network administrator decides whether sites may change the setting.

Source: WordPress.org Plugins: Classic Editor

The options are not created on activation: without classic-editor-replace the plugin defaults to the classic editor for everyone. Setting it to block with switching allowed is a gentle transition: new users get the block editor, and the classic editor stays available per post. Content written in the classic editor opens in the block editor as one Classic block, which Convert to blocks turns into real blocks. Deactivating the plugin does not change any content.

Developers can also turn the block editor off for one post type or one post with the use_block_editor_for_post_type and use_block_editor_for_post filters; the plugin uses them. Staying on the classic editor has costs: none of the features on this page (patterns, Notes, per-viewport visibility, new blocks, the visual revisions screen) work there, and the Site Editor and block themes are built on blocks regardless.