Yoast Breadcrumbs for Custom Post Types and Blog Posts

There are a couple tricky settings that affect how Yoast’s breadcrumbs display for Custom Post Types and Blog Posts. It can be a bit frustrating when breadcrumbs are not displaying correctly and you don’t know why. I figured out today, it’s all in the settings.

Custom Post Types Breadcrumbs

When creating Custom Post Types with the register_post_type( $post_type, $args ); function, you need to set argument ‘has_archive’ => true. When you do that, the archive (page that displays template archive-[post_type_slug].php or archive.php if that template doesn’t exist) will show at yourdomain.com/[post_type_slug]. This archive page link will be added to Yoast breadcrumbs when you view your singular custom post type page.

Note: replace [post_type_slug] with the $post_type value passed to register_post_type( $post_type, $args ), or the $args array value of ‘rewrite’ if you set the ‘rewrite’ value to something else.

Any plugins that create custom post types will also need archives enabled. For example, I use Events Manager for events on a number of my client sites. To get a link to your Events listing page, you need to turn on the following under Events -> Settings -> Pages [tab] -> Event List/Archives [toggle] -> Enable Archives? = Yes. You’ll also need to have ‘Events page’ in the same panel set to the page you want in your breadcrumb path.

If you have a taxonomy associated with your custom post type, you can add the post’s category to the breadcrumbs also. To set which taxonomy should show in the breadcrumbs, go to SEO-> Search Appearance -> Breadcrumbs [tab] -> ‘Taxonomy to show in breadcrumbs for content types‘ [section heading]. Each Custom Post Type should be set to the custom post type taxonomy you want in the breadcrumbs.

Note: if you check more than one category in the taxonomy you’ve selected to display in your breadcrumbs, Yoast can only display one category in your breadcrumbs. You can control which category Yoast displays by selecting a primary category (the primary category is also the one added to the page URL if you have /%category%/ in your permalinks). The “Select the primary category” select box displays below taxonomy options when you select more than one taxonomy on your post. If only one category is selected, it is automatically the primary category.

Posts (not custom post types) Breadcrumbs

Under WordPress -> Settings -> Reading -> ‘Your homepage displays’ [section heading] set ‘Posts page:’ = to the page where you want your list of posts to display. This page is controlled by the archive.php template (or a template down the template hierarchy if it exists).

The tricky bit I ran into is you also have to set SEO -> Search Appearance -> Breadcrumbs -> ‘Show Blog page’ [setting] = ‘Show‘. If you don’t do that, the breadcrumb doesn’t contain a link to your selected ‘Posts page’.

Additional Breadcrumbs Modifications

Sometimes the sitemap is impossible to replicate through these settings and you have to manually alter the Breadcrumbs. Luckily, Yoast has a hook to modify the breadcrumb links: wpseo_breadcrumb_links

For example, I have a website with the ‘Posts Page’ set to a page that is a child of another page. For some reason, Yoast breadcrumbs does not display the parent of the ‘Posts Page’ in the single post page breadcrumbs. To fix that, I added the following filter:

add_filter( 'wpseo_breadcrumb_links', 'unbox_yoast_seo_breadcrumb_append_link' );
 function unbox_yoast_seo_breadcrumb_append_link( $links ) {
     global $post;
     if( is_singular('post')){
         $breadcrumb = array(
         'url' => site_url( '/what-we-do/' ),
         'text' => 'What We Do',
       array_unshift($links, $breadcrumb); 
     return $links;

Note: $links is an array and array_unshift() adds $breadcrumb to the beginning of that array. I have ‘Anchor text for the Homepage:’ in the Yoast Breadcrumbs settings set to blank so the first element of the breadcrumbs was this parent page. Depending on where you need the extra link in the breadcrumbs you might use array_push(), add to end of array, or array_splice(), to insert into the array.

Hopefully this gets you running with Yoast Breadcrumbs so you don’t have to manually manipulate the links too much.