Rap Pages Hub Override for Yoast Breadcrumbs

Last updated on June 7, 2026

Prior to this update, Yoast breadcrumbs relied entirely on the CPT mapper, causing all content within a CPT to inherit the same archive breadcrumb regardless of context. As a result, rap-related content displayed breadcrumbs such as:

Prior to this update, Yoast breadcrumbs relied entirely on the CPT mapper, causing all content within a CPT to inherit the same archive breadcrumb regardless of context. As a result, rap-related content displayed breadcrumbs such as:

Home > Songs Featured > Krazy
Home > Artists Featured > Tupac
Home > Song Excerpts > Don’t Have to Bump This, but Please Respect It

The desired behavior was to route rap-specific content through the Rap Pages hub:

Home > Rap Pages > Krazy
Home > Rap Pages > Tupac
Home > Rap Pages > Don’t Have to Bump This, but Please Respect It

Rather than modifying the CPT mapper itself, a separate hub override layer was introduced. This preserves the mapper as the default navigation system while allowing special content collections to define their own breadcrumb destination.

New Helper Function

A helper was added to determine whether a post belongs to the Rap Pages hub:

function get_content_hub_override($post_id = 0) {

    $post_id = $post_id ?: get_the_ID();

    switch (get_post_type($post_id)) {

        case 'artist':

            if (has_term('rapper', 'artist_type', $post_id)) {
                return [
                    'title' => 'Rap Pages',
                    'url'   => home_url('/rap-pages/')
                ];
            }

            break;

        case 'song':

            if (has_term('rap', 'song_category', $post_id)) {
                return [
                    'title' => 'Rap Pages',
                    'url'   => home_url('/rap-pages/')
                ];
            }

            break;

        case 'lyric':

            if (has_term('rap', 'song_category', $post_id)) {
                return [
                    'title' => 'Rap Pages',
                    'url'   => home_url('/rap-pages/')
                ];
            }

            break;
    }

    return false;
}

Breadcrumb Override Logic

The Yoast breadcrumb filter was updated to check for a hub override before running the standard CPT mapper.

$hub_override = get_content_hub_override();

if ($hub_override && count($links) >= 3) {

    $middle = count($links) - 2;

    $links[$middle]['text'] = $hub_override['title'];
    $links[$middle]['url']  = $hub_override['url'];

    return $links;
}

Architectural Outcome

The site now uses a two-layer breadcrumb system:

1. Hub Override Layer — Handles content that belongs to a specialized navigation hub such as Rap Pages.
2. CPT Mapper Layer — Handles all standard archive breadcrumb behavior.

This approach avoids altering CPT-level metadata, prevents conflicts with non-rap content, and establishes a reusable pattern for future hub pages such as Music Pages, Philosophy Pages, Science Pages, Movie Pages, or other curated content collections. The implementation provides content-aware breadcrumbs while maintaining a centralized and scalable navigation architecture.