If you’re a WordPress developer, you’ve likely faced this frustrating scenario: you want to create a Custom Post Type (CPT) and a Taxonomy for it that share the same URL slug for SEO-friendliness. For example, you want your URL structure to be:
yourdomain.com/campaign/(The CPT archive page)yourdomain.com/campaign/post-name/(A single CPT post)yourdomain.com/campaign/category-name/(A taxonomy archive page)
However, WordPress can’t handle this structure by default. The result is that one of them (usually the taxonomy page) will return a 404 (Page Not Found) error.
This is a common problem, and today, we’ll walk through a definitive solution for it, based on a script provided by author Duy Nguyen.
What’s the Problem?
When both a Custom Post Type and its Taxonomy register the same slug, WordPress gets confused. It doesn’t know whether .../some-string/ is a post or a taxonomy term. The default rewrite rule system only prioritizes one type, making the other inaccessible.
The Solution: An Intelligent Rewrite Rule System
The solution is to intercept how WordPress handles these URLs by adding custom rewrite rules and intelligent query detection logic.
This system will:
- Prioritize Posts over Taxonomies: It will first check if the URL matches a CPT post.
- Detect and Resolve Conflicts: If no post is found, it will then check if the URL is a taxonomy archive page.
- Maintain SEO-Friendly URLs: It keeps the URL structure clean without needing extra prefixes (like
.../category/term-name/). - Ensure Compatibility: It works even if you register your CPTs and Taxonomies using popular plugins like Advanced Custom Fields (ACF).
Quick Start Guide
You can easily implement this solution in just 3 simple steps:
Step 1: Copy the Code to functions.php
Open the functions.php file in your active theme’s directory. If you are using a child theme, add it to your child theme’s functions.php.
Copy the entire content of the functions.php file from the repository here and paste it at the end of your functions.php file.
(Note: You will need to edit the CPT and Taxonomy names in the code to match your project’s setup.)
Step 2: Flush Your Permalinks
This is a critical step to make WordPress “learn” your new rewrite rules.
- Go to your WordPress Dashboard.
- Navigate to Settings > Permalinks.
- You do not need to change anything; just click the “Save Changes” button.
This action forces WordPress to flush its rewrite rule cache and apply the new rules you just added.
Step 3: Test Your URLs
Now, check your URLs:
- Access the CPT archive page (e.g.,
/campaign/) - Access a single CPT post (e.g.,
/campaign/post-name/) - Access a taxonomy archive page (e.g.,
/campaign/category-name/)
All pages should now load correctly without any 404 errors.
Conclusion
A URL slug conflict between a CPT and its taxonomy is an annoying problem, but thankfully, it’s one that can be solved cleanly. By implementing a custom rewrite rule system, you can achieve the optimal URL structure for SEO while ensuring everything functions perfectly.
A special thanks to the author, Duy Nguyen, for sharing this useful solution with the community. You can view the full technical documentation and source code on the GitHub repository right here.
