Various print blocks in drawers, ready to be used in a printing press.

Semantics matter: Choosing the right blocks for your content

Paragraphs, headings, and lists, oh my! When creating new posts and pages, it's important to choose the right tool for the job.

The editing interface in WordPress is called the “Block Editor” because it allows you to assemble various “blocks” to create your content. We break up our content into blocks like paragraphs, lists, and headings. And we make choices that let our content be pretty and readable.

But we can’t make choices only to make things pretty. It’s important that we also always choose the right (semantically correct) block for the job.

What are semantics?

When we talk about semantics (in website-speak), we mean that choices have particular meanings. Everyone knows that “red means stop!” So just like you would never make a stop sign green, there are certain rules to follow on the web.

We need to pick the right elements that convey our meaning properly, instead of unintentionally choosing elements for how they look, without realizing they mean something else.

When you choose the right blocks, everyone wins. Following semantics helps your content be more accessible and inclusive. People visiting your site can read the content clearly and easily. And the resulting code is formatted properly, so that screen-readers, search engines, and other tools can read and understand it too.

(In general, you shouldn’t have to write or read the code — I’m giving examples here for your reference.)


If something is a heading or subhead, make it a heading.

For headings, use

  • a “heading” block set at the appropriate level (see below)

Don’t use

  • a bold-text paragraph
  • a paragraph you’ve made large by changing the font-size, etc.
  • a “heading” block set at the wrong level

By choosing the Heading block, you are ensuring the resulting HTML is wrapped with properly formatted heading tags. If you were to look under the hood, the code should look like this:

<h2>My first section heading</h2>

Important: Headings need to go in order

The number of the heading you choose (like “H2” or “H4”) has semantic meaning. Never pick a number just based on the size you want something to look.

Arrange your content in order — think of an old-school English class outline.

  • In nearly all cases, the main page or post title gets the “H1” declaration.
  • So when you divide your content into sections further, start with “H2.”
  • Then, if an “H2” section has sub-divisions, they get “H3,” etc.

The resulting content is nicely divided, clear, and understandable. If you were to pull out only the headings of your document, minus all the other text, it should make a nice, clear outline that makes sense and doesn’t skip any levels.

Under the hood, you might see this:

<h2>My first section heading H2</h2>
  <p>A nice paragraph here.</p>

  <h3>Section part one H3</h3>
    <p>This section's text.</p>

  <h3>Section part two H3</h3>
    <p>This section's text.</p>


For normal paragraphs, use the standard “Paragraph” block.

For paragraphs, use

  • a “paragraph” block

Don’t use

  • a “heading” block set to H5 so the font looks pretty

By choosing the Paragraph block, you are ensuring the resulting HTML is wrapped with properly formatted paragraph tags. If you were to look under the hood, the code should look like this:

<p>Here is a nice paragraph, formatted correctly.</p>

“But I want my paragraph to be prettier!”

In the past, people often chose Headings for styling reasons alone — to make certain text bigger, different, or styled. Now there are better ways.

First start with a paragraph. Then, you could:

  • Use the “Preset size” drop-down in the Block settings to choose a different size.
  • Use the “Color settings” area in the Block settings to choose a different color (paying attention to accessibility & contrast)

Here your code is still based on a paragraph tag, but also has additional styling. If you looked under the hood, it may look something like this:

<p class="has-medium-size has-wine-color">Here is a nice paragraph, formatted correctly.</p>

Or choose a more appropriate (still semantic) block:


For things that are lists, use the standard “List” block.

For lists, use

  • a “list” block with bullets for unordered content
  • a “list” block with numbers for ordered content

Don’t use

  • a fake list in a single paragraph block using soft returns or dashes or asterisks
  • a fake list where every item is its own paragraph

By choosing the List block, you can reap the benefits of a nicely styled list (either bulleted or numbered), where all of the indentations work right and the list is clear and scannable.

You are ensuring the resulting HTML is wrapped with properly formatted list tags. If you were to look under the hood, the code should look like this:

  <li>My first list item</li>
  <li>My second list item</li>


If you have a testimonial or a nice bit of copy you want to pull out, you can use a quote block or a pullquote block.

If your quote has a citation line (naming the person who said the bit of text), use the citation area available in the block itself.

For quotes, use

  • a “quote” block
  • or a “pullquote” block
  • the citation area available in either block, if appropriate

Don’t use

  • a heading block with the quotation text set as an H4 to make the font bigger
  • a quote block with the quotation itself in the quote area, followed by “-Person name” also in the quote area (with an empty citation)

By choosing one of the Quote blocks, your quote will be styled to be both pretty and semantic.

Under the hood, the quoted text might look like this for a basic quote:

<blockquote>Something nice somebody said.</blockquote>

or like this for a quote with a citation:

<blockquote class="wp-block-quote">
  <p>Quote here</p>
  <cite>Citation here</cite>


If you have content that needs to be in a table, such as a price list or a schedule, use the table block.

Note that tables are a very particular type of HTML formatting. When you actually have a table, use a table! But don’t use them for things that aren’t tables.

For tables, use

  • for instance, a two-column, three-row table with items and prices
  • or a three-column, eight-row table with a class schedule

Don’t use

  • a list where you type the item, hit space four times, then type the price
  • an uploaded image of a table you made in another program
  • a two-column table because you want columns (use a columns block instead)
  • a complicated table to make your page layout pretty (build the layout with blocks instead)

Top photo by Erik Mclean from Pexels.

Share this post

Leave a Reply

Your email address will not be published. Required fields are marked *