How to use the Yoast SEO FAQ block outside the Gutenberg editor

An FAQ section with Schema structured data on your web-page improves user experience and can have positives effects on SEO. As an SEO Company, we often use and highly recommend “Yoast SEO” – a WordPress plugin, which also provides a nice solution for integrating FAQ’s.

Hint: If you’re unfamiliar with Yoast’s Basic Settings, follow this tutorial for the basic settings.

Yoast’s “FAQ Gutenberg Block” can be a great time-saver – by simply filling in questions and answers in a special Gutenberg block, you get them printed on your page while the Schema structured data is provided for Search Engines in the background. Sounds awesome, yet Yoast did the backbone, and left some place for creativity, which we took advantage of to implement Yoast’s FAQ in our clients’ websites.

Wait, what if we don’t use Gutenberg?!

If you have a legacy project with the classic editor (TinyMCE) or use a Pagebuider (Divi’s Visual Editor), or a page structure based on Widgets (like Genesis Framework), then you have limited access to Gutenberg, and can hardly implement Yoast’s FAQ Feature anywhere you have been planning to.

Therefore we’ve used a simple solution, which works all over WordPress – it’s called a [shortcode]. The idea is to access the Gutenberg editor and the Yoast’s FAQ block in a custom post type. Then render the custom-post-type post anywhere via the shortcode.

In other words, you implement these codes to create a custom FAQ post type and shortcode. Every FAQ post will be a list of questions-answers. The next step is to fill in the questions and answers via a FAQ Block inside the Gutenberg editor and save the post.

Now, there is a shortcode available for your new FAQ post – you can add it anywhere you want. Might be it a widget, a post or page, a Divi section, or a code block.

Here are a few questions you might want to ask:

Implementation options

Here are 2 options to implement the solution on your website: insert the code into (your child themes) functions.php file, or download and install our plugin.

Hint: We highly recommend you to add this code into your child theme. Otherwise you might loose your made changes if your theme-developer updates his theme.

1. Code for child theme

This action creates the FAQ custom post type with Gutenberg support.

add_action( 'init', function() {
    $labels = [
        'name'                => 'FAQ Sections',
        'singular_name'       => 'FAQ',
        'menu_name'           => 'FAQ Sections',
        'all_items'           => 'All FAQ',
        'view_item'           => 'View FAQ',
        'add_new_item'        => 'Add New FAQ',
        'add_new'             => 'Add New',
        'edit_item'           => 'Edit FAQ',
        'update_item'         => 'Update FAQ',
        'search_items'        => 'Search FAQ',
        'not_found'           => 'FAQ Not Found',
        'not_found_in_trash'  => 'FAQ Not found in Trash',
    ];
    $args = [
        'label'               => 'faq',
        'description'         => 'FAQ sections for further on-page implemention',
        'labels'              => $labels,
        'supports'            => [
                                    'title',
                                    'editor',
                                ],
        'hierarchical'        => false,
        'public'              => false,
        'show_in_rest'        => true,
        'show_ui'             => true,
        'show_in_menu'        => true,
        'show_in_nav_menus'   => false,
        'show_in_admin_bar'   => true,
        'menu_position'       => 5,
        'menu_icon'           => 'dashicons-portfolio',
        'can_export'          => true,
        'has_archive'         => false,
        'exclude_from_search' => true,
        'publicly_queryable'  => false,
        'capability_type'     => 'page',
    ];
    register_post_type( 'faq', $args );
}, 0);

The following code adds the short code for printing the FAQ.

add_shortcode( 'yoast-faq', function($atts) {
    if ( !$atts['id'] || !is_numeric( $atts['id'] ) ) {
        return;
    }
    $query = new WP_Query( [
        'post_type' => 'faq',
        'p' => $atts['id']
    ]);

    $result = '';
    if ( $query->have_posts() ) {
        while ( $query->have_posts() ) {
            $query->the_post();
            if ( function_exists( 'yoast_faq_block_to_schema_984628683' ) ) {
                $result = yoast_faq_block_to_schema_984628683(
                    get_the_content()
                );
            } else {
                $result = get_the_content();
            }
        }
    }
    
    wp_reset_postdata();
    return $result;
});

Basically, you add [yoast-faq id=FAQpageID] to the place, where you want to display your FAQ.

For example, if you want to use the FAQ inside the Divi Builder, it would look like this:

The codes above are pretty enough for printing the FAQ on a page. Scheme generating process in Yoast works separately from get_the_content() function, though. The next code takes the JSON data from the FAQ block and converts it to the FAQ structured data.

function yoast_faq_block_to_schema_984628683($result) {
    if ( !preg_match( '/\<\!--\s+wp\:yoast\/faq-block\s+(.*?)\s+--\>/i', $result, $matches ) ) {
        return;
    }

    $data = json_decode( $matches[1] );
    $structured = [];
    foreach ( $data->questions as $k => $v ) {
        $structured[] = [
            '@type' => 'Question',
            'name' => strip_tags( $v->jsonQuestion ),
            'acceptedAnswer' => [
                '@type' => 'Answer',
                'text' => $v->jsonAnswer
            ]
        ];
    }
    $structured = [
        '@context' => 'https://schema.org',
        '@type' => 'FAQPage',
        'mainEntity' => $structured
    ];
    $result = preg_replace( '/\<\!--\s*(.*?)\s*--\>/i', '', $result );
    $result .= '<script type="application/ld+json">'.json_encode( $structured, JSON_PRETTY_PRINT ).'</script>';
    
    return $result;
}

All the codes above normally gotta be added to your WordPress child theme functions.php file. Unless you know better.

2. Install our plugin

Basically, the plugin contains the codes above, wrapped with a PHP class, a few improvements and a small feature, displaying the shortcodes right in the list of FAQ posts.

This might be an option if you’re not able to create a child theme by yourself.

A few remarks

The solution Schema is valid and recommended by Google references, but not integrated into Yoast generated Schema, as it would be natively. Yoast hooks allow integration, but as Schema doesn’t prohibit a few structured data sets, we decided to keep it the simplest.

Using other Gutenberg blocks in the FAQ custom-post-type posts is unpredictable – at least avoid the complex ones.

There is a solution, though, which wasn’t widely tested – to render the shortcode before it is rendered with the_content(). Use it at your own risk.

add_filter( 'the_content', function($content) {
    $regexp = '/\[yoast-faq[^\]]*\]/i';
    if ( preg_match( $regexp, $content, $matches ) ) {
        $rendered = do_shortcode( $matches[0] );
        $content = str_replace( $matches[0], $rendered, $content );
    }
    return $content;
}, 0 );

These codes don’t effect the Yoast’s FAQ styling in any way. To style, and make it toggle or accordion, read Yoast’s FAQ to Accordion