Tag: Permalinks

Change Taxonomy Rewrite Slug (Without Breaking Links)

When working with WordPress custom taxonomies, you might want to change the URL slug used in the taxonomy archive URLs. However, changing the rewrite slug directly can break existing links, causing 404 errors and hurting SEO. This tutorial shows you how to safely change a taxonomy rewrite slug without breaking existing links, ensuring smooth transitions and preserving SEO value.

When to Use This

• You want to update the URL structure of a custom taxonomy for branding or SEO reasons.
• You need to rename the slug to better reflect content or user expectations.
• You want to avoid breaking existing links by redirecting old URLs to the new slug.
• You are comfortable adding code to your theme’s functions.php or creating a mini-plugin.

Quick Fix: Change Taxonomy Rewrite Slug Safely

1. Update the taxonomy registration with the new rewrite slug.
2. Flush rewrite rules once after the change.
3. Add a redirect from the old slug URL to the new slug URL to avoid 404s.
4. Test the old and new URLs to confirm proper redirection and no broken links.

Why This Happens

WordPress generates URLs for taxonomies based on the rewrite['slug'] parameter set during taxonomy registration. Changing this slug changes the URL structure. However, WordPress does not automatically redirect old URLs to the new ones, so visitors and search engines hitting the old URLs get 404 errors. This breaks links and negatively impacts SEO.

To fix this, you must update the slug in the taxonomy registration and add a redirect from the old slug to the new slug. Flushing rewrite rules ensures WordPress recognizes the new URL structure.

Step-by-Step: Change Taxonomy Rewrite Slug Without Breaking Links

1. Update Taxonomy Registration

Locate where your taxonomy is registered (usually in your theme’s functions.php or a plugin). Change the rewrite['slug'] to the new slug.

function my_custom_taxonomy() {
    $labels = array(
        'name' ='Genres',
        'singular_name' ='Genre',
    );

    $args = array(
        'labels' =$labels,
        'public' =true,
        'rewrite' =array(
            'slug' ='new-genre-slug', // Change this to your new slug
            'with_front' =false,
        ),
        'hierarchical' =true,
    );

    register_taxonomy('genre', 'post', $args);
}
add_action('init', 'my_custom_taxonomy', 0);

2. Flush Rewrite Rules

Flush rewrite rules once after updating the slug. The easiest way is to visit Settings > Permalinks in the WordPress admin and click “Save Changes” without modifying anything.

Alternatively, flush programmatically (only once):

function my_flush_rewrite_rules() {
    my_custom_taxonomy();
    flush_rewrite_rules();
}
add_action('after_switch_theme', 'my_flush_rewrite_rules');

3. Add Redirect from Old Slug to New Slug

Add a redirect rule to send visitors and search engines from the old taxonomy slug URL to the new one. This prevents 404 errors and preserves SEO.

function redirect_old_taxonomy_slug() {
    if (is_tax('genre')) {
        $current_slug = get_query_var('taxonomy');
        $term_slug = get_query_var('term');

        // Old slug URL pattern
        $old_slug = 'old-genre-slug';
        $new_slug = 'new-genre-slug';

        // Check if current URL uses old slug
        if (strpos($_SERVER['REQUEST_URI'], '/' . $old_slug . '/') !== false) {
            $new_url = home_url('/' . $new_slug . '/' . $term_slug . '/');
            wp_redirect($new_url, 301);
            exit;
        }
    }
}
add_action('template_redirect', 'redirect_old_taxonomy_slug');

4. Test URLs

• Visit an old taxonomy URL (e.g., https://example.com/old-genre-slug/term-name/) and confirm it redirects to the new URL.
• Visit the new taxonomy URL (e.g., https://example.com/new-genre-slug/term-name/) and confirm it loads correctly.
• Check for any 404 errors or broken links.

Variations

• Non-hierarchical taxonomies: The same approach applies; just adjust the taxonomy name and slugs.
• Multiple taxonomies: Add similar redirect logic for each taxonomy slug change.
• Using a plugin: Some redirection plugins can handle old-to-new slug redirects without code.
• Advanced redirects: Use add_rewrite_rule() for complex URL structures.

Works On

Environment	Notes
Apache	Works seamlessly with mod_rewrite and WordPress permalinks.
Nginx	Ensure permalinks are configured correctly; redirects work as expected.
LiteSpeed	Compatible with WordPress rewrite rules and redirects.
cPanel / Plesk	Standard WordPress setup; no additional config needed.

FAQ

Q1: Can I change the taxonomy slug without adding a redirect?

A: Technically yes, but old URLs will break and return 404 errors, which harms user experience and SEO. Always add redirects when changing slugs.

Q2: How do I find the current taxonomy slug?

A: Check the rewrite['slug'] parameter in your taxonomy registration code or visit the taxonomy archive page and inspect the URL.

Q3: Can I flush rewrite rules programmatically?

A: Yes, but only do it once after changing the slug to avoid performance issues. Use flush_rewrite_rules() inside an activation hook or after your taxonomy registration.

Q4: Will this method work for built-in tax

…