WordPress Block Markup Comments: Why They Exist

WordPress block markup comments identify block boundaries inside saved content. They also store selected block attributes as JSON. Browsers ignore them, while WordPress reads their structure.

Without these comments, saved HTML would lose reliable block identity. WordPress could guess from tags and classes. Those clues remain ambiguous and easily changed.

The comments therefore preserve ordinary HTML and structured editing together. They are delimiters, not decorative notes. Removing them changes how the editor understands content.

A block comment in plain English

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">A centred paragraph.</p>
<!-- /wp:paragraph -->

The opening comment says a Paragraph block starts here. Its JSON records the selected alignment. The closing comment marks the block’s end.

The paragraph element remains normal HTML. Its class represents the same saved choice. WordPress can compare registered output with this stored markup.

The four parts of an opening delimiter

1. The HTML comment opener starts an invisible comment.
2. The wp: prefix identifies block syntax.
3. The block name identifies the registered type.
4. Optional JSON carries attributes stored outside inner markup.

Whitespace separates the name and JSON object. The comment then closes normally. Paired blocks receive a matching closing delimiter containing a slash.

The official markup guide calls these block delimiter comments. That name describes their structural purpose accurately.

Why comments work better than custom elements

HTML comments can surround almost any valid markup. They do not impose another visible wrapper. That matters for layout, semantics, and existing theme CSS.

Custom elements would alter the document tree. Data attributes would require predictable wrapper elements. Many blocks cannot share one universal wrapper pattern.

Comments also survive inside the database as text. Browsers safely ignore them. WordPress can parse them before sending final output.

This design supports graceful degradation. Saved HTML can remain readable without editor code. The delimiters preserve richer structure when WordPress understands them.

Core names use shorter syntax

Registered block names normally contain a namespace. Core names use the core namespace internally. Serialized comments omit that namespace for brevity.

<!-- wp:heading -->
<h2 class="wp-block-heading">Example heading</h2>
<!-- /wp:heading -->

The registered name is core/heading. Its delimiter uses only heading. Custom blocks retain both namespace and slug.

<!-- wp:acme/notice -->
<div class="wp-block-acme-notice">Check this detail.</div>
<!-- /wp:acme/notice -->

The namespace prevents collisions. Another plugin can register its own notice block. Their names and delimiters remain distinct.

Some blocks use self-closing comments

A block without saved inner HTML can use one self-closing delimiter. Dynamic blocks commonly use this representation. Their server callback generates frontend markup later.

<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->

The comment identifies the block and stores its settings. No cached list appears inside it. Current posts are queried during rendering.

Self-closing syntax does not always mean dynamic rendering. It means no inner block content was serialized. Registration determines actual frontend behaviour.

Nested blocks create nested delimiters

Container blocks save child delimiters inside their own boundaries. The order forms a tree. Every opening delimiter must match the correct closing delimiter.

<!-- wp:group -->
<div class="wp-block-group">
  <!-- wp:paragraph -->
  <p>Nested content.</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

WordPress records children separately while preserving surrounding HTML. A mismatched closer can corrupt the parsed tree. Raw edits therefore need careful nesting.

List View presents this hierarchy visually. The saved comments carry the underlying boundaries. Wrapper indentation only helps humans and is not authoritative.

Where WordPress stores the comments

Posts and pages normally store block markup within post_content. That field contains comments and saved HTML together. WordPress does not require one database row per block. We settle it in what a block contains and stores.

Templates, template parts, and patterns can use the same markup representation. Their storage location may differ. The delimiter grammar remains recognisable across contexts.

This single-text format keeps content portable through familiar WordPress tools. Exports can carry block markup. Revisions can compare the serialized document. We answer that in what “Unexpected or invalid content” means.

It also means careless search-and-replace can damage many blocks. Treat serialized content as structured data. Back up before bulk transformations.

How the parser reads block comments

WordPress scans content for recognised delimiter syntax. It builds parsed block records from names, attributes, inner blocks, and HTML fragments. The full walkthrough is in how to move blocks between WordPress sites.

The parse_blocks() reference documents the server entry point. Filters can replace its parser class. Most sites use the core parser.

Freeform HTML between blocks is preserved too. The parser can represent content without a named block. Classic content therefore remains compatible with the wider pipeline.

Parsing does not automatically render every block. It creates structure first. Later processing chooses saved markup or registered dynamic output.

How serialization rebuilds the document

Serialization turns parsed blocks back into delimiter comments and content. It preserves the block name, attributes, inner blocks, and suitable inner HTML.

The serialize_block() reference shows the server function. Client packages provide corresponding parsing and serialization behaviour.

A clean round trip should preserve meaning. Formatting may change. Semantic differences indicate lost attributes, altered markup, or parser mistakes.

Do not build delimiter strings with casual concatenation. Use WordPress parsing and serialization APIs. They handle structure and attribute escaping consistently.

What visitors receive

WordPress processes block content before normal frontend display. Static blocks contribute their saved HTML. Dynamic blocks contribute current rendered output.

Delimiter comments are editing structure, not visible interface. Visitors generally receive rendered markup without those boundaries. Page source can still contain unrelated HTML comments.

Caches usually store processed page output. The database retains serialized block content. Confusing those layers can mislead debugging.

Why attributes appear inside comments

Some settings lack a natural HTML location. Query counts, toggle states, and internal options may not belong visibly. Comment JSON stores them beside the block.

Other attributes derive from saved markup. Text can come from an element. Image URLs can come from HTML attributes.

Comment storage is only one attribute strategy. Our block attribute guide compares all sources. It also covers defaults and type validation.

Comments enable static block validation

The delimiter identifies which registered saving function should reproduce the block. WordPress compares expected markup with saved markup when editing static blocks.

A meaningful mismatch triggers an invalid-content warning. This protects content from silent reinterpretation. It also exposes incompatible code changes quickly.

The comments alone do not prove validity. Inner HTML must match registered expectations. Stored attributes must also parse into accepted types.

Dynamic blocks returning no saved HTML skip normal markup validation. Their comment still supplies identity and attributes. Rendering occurs on the server.

What happens when a block is unregistered

The delimiter remains inside saved content. However, the editor lacks the registered type. It cannot show the original editing interface.

Saved static HTML may still appear on the frontend. A comment-only dynamic block has no fallback markup. Its visible output can disappear.

Reactivating the correct plugin can restore registration. Do not immediately convert missing blocks. Conversion can discard recoverable structured data.

Our plugin deactivation guide provides a safe staging test. Run it before adopting critical blocks.

Can you edit block comments manually?

Yes, through the code editor or external tools. However, manual edits bypass block controls. One missing slash or brace can change the document tree.

Attribute JSON requires valid quoting and escaping. Names must match registration. Closing delimiters must match their openings and nesting order.

Edit raw syntax only when the risk is justified. Preserve a revision first. Reopen the visual editor and inspect every changed block.

For bulk changes, parse blocks programmatically. Modify structured records. Then serialize them through supported APIs and verify the result.

Why regular expressions are risky

Nested block syntax is recursive. Regular expressions struggle with arbitrary nesting and escaped attribute content. Simple replacements can cross block boundaries.

Similar text can appear inside code examples or Custom HTML. A blind replacement cannot understand intention. Structured parsing narrows the mutation correctly.

A regex may suit a tightly verified final string change. It should follow backups and scoped queries. Reparse every edited document afterward.

Block delimiters and ordinary comments differ

Developers also place ordinary HTML comments inside content and templates. Those comments can contain explanations, markers, or tool instructions. They lack the recognised wp: delimiter grammar.

The block parser preserves surrounding freeform fragments where appropriate. It does not register every comment as a block. Exact syntax carries that meaning.

Do not reuse block prefixes for unrelated annotations. Future parsers may interpret valid-looking syntax. Choose a clearly separate project prefix for internal markers.

Minifiers and migration tools sometimes remove ordinary comments. They may also remove block delimiters accidentally. Exclude stored WordPress content from destructive HTML cleanup.

How revisions help after delimiter damage

WordPress revisions can preserve earlier post_content values. That includes delimiter comments and saved HTML. A revision may therefore restore complete block structure. The longer version is in WordPress revisions and autosaves in the block editor.

Compare revisions before restoring the entire document. Later text changes might be valuable. Copying only one repaired block can preserve unrelated edits.

Database backups provide another recovery layer. They help when revisions were limited or removed. Confirm the backup predates the damaging operation.

After restoration, reopen the editor without saving immediately. Check List View and each warning. Then preview the frontend before accepting the repair.

Common delimiter mistakes

• An opening block lacks its matching closer.
• A closing delimiter names the wrong block.
• A nested block closes after its parent.
• Attribute JSON contains invalid quotes or commas.
• A custom block omits its namespace.
• A paired block becomes self-closing accidentally.
• Saved HTML moves outside the intended boundaries.
• A search replacement changes comments inside code examples.
• A plugin update changes saved markup without deprecation.
• Sanitisation removes comments from imported content.

Symptoms vary. Blocks can become invalid, missing, flattened, or freeform. The frontend may still look correct while editing structure is damaged.

A safe debugging sequence

1. Create a revision or database backup.
2. Copy the affected block through the editor.
3. Inspect its raw delimiter and inner HTML.
4. Confirm the registered block name exists.
5. Validate the opening comment’s JSON.
6. Check paired delimiters and nesting order.
7. Compare saved markup with current output.
8. Test with conflicting filters disabled.
9. Restore the provider before converting anything.
10. Save only after previewing the repair.

Use a minimal duplicate during investigation. Saving a damaged production page can rewrite recoverable content. A revision is cheaper than reconstruction.

Comments in patterns and templates

Block patterns use delimiter syntax to describe inserted block arrangements. Theme templates and template parts use the same basic representation.

That common grammar enables reuse across editing surfaces. A pattern can contain nested core and custom blocks. Availability still depends on registration.

Theme authors should avoid removing required plugin dependencies silently. Missing custom blocks can weaken templates. Provide fallbacks for essential visible content.

Security and sanitisation considerations

Block comments do not make unsafe HTML safe. WordPress still applies capabilities and sanitisation. Rendering code must escape output for its context.

Attribute JSON is stored input. Dynamic callbacks should validate expected types and values. Never treat serialized settings as trusted simply because WordPress parsed them.

Import tools may strip comments while preserving HTML. The page can look intact afterward. Its block editing structure may still be lost.

A portability test for block markup

• Create representative content with every custom block.
• Export and import it into a staging site.
• Confirm delimiter comments survive unchanged.
• Open imported content with providers active.
• Compare editor hierarchy and frontend output.
• Deactivate providers and inspect saved fallbacks.
• Reactivate providers before editing missing blocks.
• Document any required migration tools.

This test reveals whether tooling preserves structure. Visual comparison alone misses delimiter loss. Always reopen imported content inside the editor.

Frequently asked questions

The verdict

Readable fallback markup reduces dependency risk. It cannot preserve every interactive feature after deactivation. Test each free WP Block Suite plugin first. Then review the $299 lifetime suite if several Pro plugins suit your stack.