Theming Gutenberg: the How-to block

With the launch of Yoast SEO 8.0, we’ve released our first real integration with Gutenberg. Now, with Yoast SEO 8.2 we took the first step into how to combine the power of Gutenberg with the field of SEO. More specific: the user-friendly implementation and usage of structured data.

I won’t go into the technicalities, so if you are new to structured data, read all about it here. But what we did – in short – is introduce a content block that makes it easy to add support for specific types of content. In this case the How-to block.

The How-to block

With our How-to block, you can now add a specific step-by-step set of instructions to a post or page. Or as phrases it: “An instruction that explains how to achieve a result by performing a sequence of steps.”

This list gets served as a structured data code snippet to help search engines get a better understanding of the content of your page. And in the future, Google will show a How-to block as such in its search results. So, that’s a lot of technical stuff happening in the background. But how does this block actually look on the front-end of your website? Well, that’s something you control yourself!

Interested in more in-depth information about specific HowTo structured data? Read all about it here.

HowTo as a Google search result

An example of how our HowTo block is displayed in Google’s search results

The markup

Our How-to block can be broken down into three elements. The total time (a paragraph), the description (a paragraph) and the list of steps (an ordered list). Each step is subsequently treated as a section consisting of a name and a paragraph with the actual explanation. The markup:


<div class="schema-how-to wp-block-yoast-how-to-block">

Time needed


<ol class="schema-how-to-steps">

<li class="schema-how-to-step">
<strong class="schema-how-to-step-name">Name of step 1</strong>

Step explanation


<li class="schema-how-to-step">
<strong class="schema-how-to-step-name">Name of step 2</strong>

Step explanation


<li class="schema-how-to-step">
<strong class="schema-how-to-step-name">Name of step 3</strong>

Step explanation





We’ve set some reasonable defaults for the block (such as emphasizing the name of a step by wrapping it inside a <strong> tag). Besides that, it will inherit the styling you have in place for these standard HTML elements and be displayed as a standard numbered list (see example below). If you want to take the styling of the block a little further and actually customize it, then read on! There are a few approaches that we want to walk you through.

HowTo - unthemed

Example of the HowTo block as a standard numbered list

Styling the How-to block

As a WordPress theme developer or a web designer, we assume that you have a basic understanding of CSS. If you want to dive deeper into CSS or a preprocessor like SASS or LESS, we believe that or might be a good starting point.

Styling the supplied class names

As you can see in the code block above, all the elements within the How-to block come with their own specific class names, which can be targeted and styled to fit your needs. To sum it up:

  • The ‘shema-how-to’ class for the block itself
  • The ‘schema-how-to-total-time’ class for the time required to time follow the instructions
  • The ‘schema-how-to-description’ class for the block description
  • The ‘schema-how-to-steps’ class for the list of instructions
  • The ‘schema-how-to-step’ class for an instruction section
  • The ‘schema-how-to-step-name’ class for the name of an instruction step
  • The ‘schema-how-to-step-text’ class for the actual explanation of a step

Styling by setting your own custom class names

It’s likely that you have a specific convention for naming different HTML elements in your projects, or that you already have a utility class in place that helps you style all your list elements. If that is the case and you don’t want to work with the supplied class names, it’s possible to add your own custom class name to the block.

HowTo block settings

The How-to block settings in the Gutenberg sidebar

In the image above we’ve added two custom class names (‘list-class and ‘block-class’). Under ‘Settings’ we’ve added a class name that only applies to the list element. Under ‘Advanced’ we’ve added an additional class to the block itself. Note that these class names will be added to the already supplied class names.

The How-to block on

If you’re a regular visitor of our knowledge base, you might have noticed that we have specific styling in place to emphasize our step-by-step instructions (e.g. how to install Yoast SEO Premium).

HowTo - themed

The HowTo Gutenblock in action on

Interested in how we did this? The code block below shows the lines of CSS (or actually SCSS) we have in place to achieve the above result.

[code].schema-how-to-total-time {
font-style: italic;

ol.schema-how-to-steps {
list-style-type: none;
counter-reset: rowNumber;
margin-left: 0;

.schema-how-to-step {
position: relative;
padding-left: 48px;

&:not(:empty):before {
display: inline-block;
position: absolute;
width: 30px;
left: 0;
content: counter(rowNumber);
counter-increment: rowNumber;
font-size: 14px;
color: $color-white;
text-align: center;
line-height: 1;
padding: 8px;
background: $color-green-blue;
border-radius: 100%;

img {
display: block;

What’s next?

We’re planning on releasing a lot more structured data related content blocks, that integrate with Yoast SEO. Next up is the FAQ block! Besides that, we’ll keep you posted on the possible release dates and will return with more in-depth tutorials on how to work with these blocks and style them to fit your needs. Interested in what Gutenberg can do for you? Read Joost and Omar’s vision on the future of Gutenberg here.

Coming up next!

5 Responses to Theming Gutenberg: the How-to block

  1. Manuel Hudec
    Manuel Hudec  • 6 years ago

    Thanks for the answer. I posted it there. Greetings

  2. Manuel Hudec
    Manuel Hudec  • 6 years ago

    It would be really helpful if you could set an HTML anchor for the individual steps. Then you could refer to individual steps in the description and link them directly.

    Have you ever thought about it?

  3. Gracious Store
    Gracious Store  • 6 years ago

    You targeted this post for people who are “code savvy”, not for those who do not have background in coding

    • Luc Kickken

      Hi! You’re right that the basis of this post is somewhat technical. Here, on our Dev blog, we usually address topics that are a bit more ‘code savvy’. With how the content block is set up as of now, I’m afraid you do need some basic understanding of HTML/CSS and some experience with how WordPress themes are structured to style it the way you want. I think the scope of the post would have been too broad if we addressed the basics of CSS. The post does contain some directions to resources where you can learn more about HTML and CSS, if you’re interested.

      Is there anything you struggle with in particular?