Category listing page with custom taxonomy


I think this issue has been covered in this discussion: Using Roots with a custom taxonomy

However, I was unable to find a solution to this specific issue. The sage version I am using is 8.5.3.

What I am trying to is create a custom post type, with custom taxonomy (in this case, a custom category).

I think this page according to the wordpress template hierarchy should be stored in the file taxonomy-[custom-taxonomy].php or in my case taxonomy-fcategory.php

However, this results in a 404 page. As Ben Word has mentioned:

A 404 has nothing to do with templates, because at the lowest level Roots will be using index.php for taxonomy and tag templates.

I have tried category and archive alternatives and during each change I ensured I resaved the permalinks to store any wordpress rewrite changes, but unfortunately I run into the same problem.

Is it possible to help with this issue?

Kind regards


Hi craig, sorry as far as I know I didnt withdraw this post. Is this what you meant?

Sorry I was a bit hasty in my reply, I suggested checking you flushed permalinks but totally missed that you’d tried that, so withdrew my post. Some other suggestions would be:

  • Make sure you don’t have an existing page/post with the same page slug reserved as the taxonomy / taxonomy archive
  • Eliminate browser cache / server cache of the 404 after flushing rewrites - i.e. in chrome inspector select disable cache
  • Make sure that the taxonomy file shares the slug and not the post type name which is registered
  • Confirm your custom post type and taxonomy is working pragmatically i.e. taxonomy_exists and get_post_type

Hi craig,

Thanks for the quick responses.

I have ensured that a page/post with same page slug does not exist. I am testing with custom taxonomy: getting-started.
I have disabled the cache as per your instructions in the chrome inspector
I have created a file taxonomy-getting-started.php and re-saved the permalinks.
The page goes to the 404 page, I testing taxonomy_exists(‘fcategory’) and this returns true. However I couldnt test the post type as it was a 404 page.

Do you need any additional information with this issue?

Could you share the code for setting up both the taxonomy and the custom post type?

Sure, custom post type:

$labels = array(
‘name’ => _x( ‘FAQs’, ‘FAQ’, ‘faq’ ),
‘singular_name’ => _x( ‘FAQs’, ‘FAQ’, ‘faq’ ),
‘name_admin_bar’ => _x( ‘FAQ’, ‘FAQ’, ‘faq’ ),
‘add_new’ => _x( ‘Add New’, ‘FAQ’, ‘faq’ ),
‘new_item’ => __( ‘New FAQ’, ‘faq’ ),
‘edit_item’ => __( ‘Edit FAQ’, ‘faq’ ),
‘view_item’ => __( ‘View FAQ’, ‘faq’ ),
‘all_items’ => __( ‘All FAQs’, ‘faq’ ),
‘search_items’ => __( ‘Search FAQs’, ‘faq’ ),
‘parent_item_colon’ => __( ‘Parent FAQs:’, ‘faq’ ),
‘not_found’ => __( ‘No FAQs found.’, ‘faq’ ),
‘not_found_in_trash’ => __( ‘No FAQs found in Trash.’, ‘faq’ )

$args = array(
‘labels’ => $labels,
‘description’ => __( ‘Description.’, ‘faq’ ),
‘public’ => true,
‘publicly_queryable’ => true,
‘show_ui’ => true,
‘show_in_menu’ => true,
‘query_var’ => true,
‘rewrite’ => array( ‘slug’ => ‘faqs/%category%’, ‘with_front’ => false ),
‘capability_type’ => ‘post’,
‘has_archive’ => true,
‘hierarchical’ => false,
‘menu_position’ => 24,
‘menu_icon’ => ‘dashicons-editor-help’,
‘supports’ => array( ‘title’, ‘excerpt’ )

register_post_type( ‘faq’, $args );

custom taxonomy:

register_taxonomy( ‘fcategory’, ‘faq’, array(
‘public’ => true,
‘publicly_queryable’ => false,
‘hierarchical’ => true,
‘has_archive’ => true,
‘show_admin_column’ => true,
‘query_var’ => true,
‘rewrite’ => array(
‘slug’ => ‘faqs’,
‘with_front’ => false,
) );

I hope this helps, apologies I was not sure if I needed to enclose the code with specific tags.

Formatting code
You can use the code block in the editor screen which is indicated by </> or alternatively you can use three backticks after a line break to open a block of code, and three back ticks on a new line to close. More info on formatting here:

Custom Post Type
In this line of code

‘rewrite’ => array( ‘slug’ => ‘faqs/%category%’, ‘with_front’ => false ), 

What does %category% aim to solve?

I’d suggest that this is changed to

‘rewrite’ => array( ‘slug’ => ‘faqs’, ‘with_front’ => false ), 

If you are looking for a custom rewrite then this should be done using a method similar to:

While you’re getting your Custom Post Type and Taxonomy off the ground I would leave custom rewrites until you have the basics up and running

You register your taxonomy as fcategory, however you later change the slug to faqs which is already reserved as a slug for your custom post type above. How would WordPress know what is a custom post type and a taxonomy?

To eliminate this overlap alter your slugs or custom post type and taxonomy names respectively. For example the below would work:

register_taxonomy( ‘fcategory’, ‘faq’, array(
    ‘public’ => true,
    ‘publicly_queryable’ => false,
    ‘hierarchical’ => true,
    ‘has_archive’ => true,
    ‘show_admin_column’ => true,
    ‘query_var’ => true,
    ‘rewrite’ => array(
        ‘slug’ => ‘fcategory’,
        ‘with_front’ => false,
) );

Files which will load correctly:
single-faq.php -> Will show custom post type data if any exists
taxonomy-fcategory.php Will show an archive of all posts in this taxonomy if any exist

When testing the above files bare in mind you may have to alter the default loop, so to progressively test I always start with a simple hello world, or var_dump, then go on and do any loop changes to include different post types

Once the above is working I would look at changing your rewrites progressively too

Thanks for the formatting code tip. Yeah, I didnt want add a layer of complexity on the initial post of the issue, but I am also trying to rewrite urls so for each faq custom post type the url should read /faqs/[custom taxonomy]/[post name].

That was a good spot, with the slug of the taxonomy and your right that would have caused a conflict as the cpt and the taxonomy would be pointing to the same url.

To keep thing simple, I have removed the rewrite condition on the slug (%category%) for the cpt and updated the slug for the category to fcategory.

I have saved the permalinks and gone to the post /faqs/getting-started but a 404 error page is produced.

My var dump query reads:

SELECT  wpprefix_posts.* FROM wpprefix_posts  WHERE 1=1  AND wpprefix_posts.post_name = 'getting-started' AND wpprefix_posts.post_type = 'faq'  ORDER BY wpprefix_posts.menu_order ASC

I should also add that I have disabled my plugins in case of any conflict.

Just to confirm:

  • You have created both files mentioned single-faq.php and taxonomy-fcategory.php
  • You have created a new post under FAQs - to eliminate any stale data using old url structures
  • Your permalink structure is /%postname%/
  • There are no existing posts, pages, or taxonomies reserving your new FAQ test URL
  • There are no redirect rules, caching, or other rewrites kicking in
  • Your rewriting config is above board for nginx / apache at server level
  • Your faq page is not set as the front page or page for posts, nor does it have a template assigned

On a blank theme this works as expected if the things mentioned are above board.

For your end result you may find this useful:

Sorry Craig, I dont think I have been as clear as I could be so far.

I was reading your previous reply and noticed in this scenario I would like the slug to be faqs for the cpt and the taxonomy (which as you mentioned causes a conflict).

To confirm what I am trying to achieve:

custom taxonomy: /faqs/[custom taxonomy]
FAQ posts: /faqs/[custom taxonomy]/postname

To answer your points:

  • No, there is single.php file which routes to content-single. Not sure if this is correct, but I have followed this principle and created content-single-faq.php and taxonomy-fcategory.php
  • I did not previously, but I have created a new post for the CPT this time around.
  • My permalink structure is /blog/%postname%/
  • I can confirm that there are no existing posts, pages, or taxonomies reserving your new FAQ test URL
  • Other than the slug rewrites on the category and CPT, there are no redirect rules, caching, or other rewrites kicking in.
  • My current installation is running from local machine on vagrant which uses nginx. However I just use the wordpress and have not configured any special requirements in the nginx config for vagrant.
  • I can confirm the faq page is not set as the front page or page for posts, nor does it have a template assigned.

Thanks for the link, I will take a look into.

From these details, I am not sure if you can spot anything that will be the cause for the 404 page?

If all else fails, I will try to add the same structure to a new install and see if that works.

This could be the root of your issues along with the usage of 'with_front' => false in your config for the faq custom post type. If for example you change your permalink type to /%postname%/and then prefix just your posts with /blog/ at a later stage you may have less friction when rewriting your Custom Post Type and Taxonomy.

Because of the complexity of your config it’s difficult to suggest a fix without access to the full code base. I imagine though, that progressive development will be your friend here, and that Sage isn’t the cause for your 404s

I appreciate your help with this task. Ironically, I have already read through the post that you suggested prior to submitting this issue today.

Like you mentioned, I think it would be best if I took a step back and see if I can get the structure right for a blank sage theme and take it step by step.

I’ll keep the issue open for now, so that I can update it with a solution

1 Like

When I’ve run into issues w/r/t using URLs that don’t line up well with how WP prefers to do things, I’ve found Cortex to be very, very helpful, as it allow you to just directly connect custom queries to custom routes:

Thanks @alwaysblank, I’ll try a clean install first and then I’ll try that and let you know if it has solved this issue.


After running a clean install, I was able to find a solution to issue.

Note: This is an issue that is linked to custom taxonomy for Wordpress and is not related to the routing on sage.

However, whilst looking online for a solution this has proven problematic for a lot of developers and for clarity I will explain the solution here.

First of all my goals are:

  • To set up a custom post type (faqs). The posts should have a URL of /faqs/[custom taxonomy]/postname
  • To set up custom taxonomy as a listing page that has its own template. The URL should be /faqs/[custom taxonomy]

To do this, you need to register your taxonomy before your custom post type.

register_taxonomy( 'faq-category', 'faq', array(
  'public'             => true,
  'publicly_queryable' => true,
  'hierarchical'       => true,
  'has_archive'        => true,
  'show_admin_column'  => true,
  'query_var'          => true,
  'rewrite'            => array(
    'slug'       => 'faqs',
    'with_front' => false,

Register the taxonomy name and ensure that the options public and public_queryable are set to true. Otherwise, your category page will redirect to the homepage. For the slug make this the base name for your custom post structure. In my case, this is faqs.

$labels = array(
    'name'               => _x( 'FAQs', 'FAQ', 'faq' ),
    'singular_name'      => _x( 'FAQs', 'FAQ', 'faq' ),
    'name_admin_bar'     => _x( 'FAQ', 'FAQ', 'faq' ),
    'add_new'            => _x( 'Add New', 'FAQ', 'faq' ),
    'new_item'           => __( 'New FAQ', 'faq' ),
    'edit_item'          => __( 'Edit FAQ', 'faq' ),
    'view_item'          => __( 'View FAQ', 'faq' ),
    'all_items'          => __( 'All FAQs', 'faq' ),
    'search_items'       => __( 'Search FAQs', 'faq' ),
    'parent_item_colon'  => __( 'Parent FAQs:', 'faq' ),
    'not_found'          => __( 'No FAQs found.', 'faq' ),
    'not_found_in_trash' => __( 'No FAQs found in Trash.', 'faq' )

$args = array(
    'labels'             => $labels,
    'description'        => __( 'Description.', 'faq' ),
    'public'             => true,
    'publicly_queryable' => true,
    'show_ui'            => true,
    'show_in_menu'       => true,
    'query_var'          => true,
    'rewrite'            => array( 'slug' => 'faqs/%category%', 'with_front' => false ),
    'capability_type'    => 'post',
    'has_archive'        => 'faq-category',
    'hierarchical'       => false,
    'menu_position'      => 24,
    'menu_icon'          => 'dashicons-editor-help',
    'supports'           => array( 'title', 'excerpt' )

register_post_type( 'faq', $args );

When registering the custom post type, add /%category% to the rewrite slug. This will be used in the following function to add the custom taxonomy to the permalink structure.

At this point, it is important to set with_front to false if in my case you have a permalink structure that is not /%postname% (I also needed to facilitate a /blog/%postname% permalink structure).

Lastly, set the has_archive option to the name of your custom taxonomy. this will be used for your custom taxonomy page. In my case, I have created taxonomy-faq-category.php

To rewrite the url to custom taxonomy permalink structure, I used this function:

// to add faq custom taxonomy to faq links - for later
function add_category_to_url( $post_link, $id = 0 ){
    $post = get_post($id);  
    if ( is_object( $post ) ){
        $terms = wp_get_object_terms( $post->ID, 'faq-category' );
        if( $terms ){
            return str_replace( '%category%' , $terms[0]->slug , $post_link );
        if(!$terms && ($post->post_type == 'faq')) {
          return str_replace( '%category%/' , '' , $post_link );
    return $post_link;  
add_filter( 'post_type_link', 'add_category_to_url', 1, 3 );

Additionally, make sure you save the permalinks under settings->permalinks as you make changes to your custom taxonomy or custom post type to ensure any url rewrites are updated.

The following links have been helpful:

Also last but not least many thanks to @craigpearson & @alwaysblank for offering their help with this issue.


Glad you managed to find a solution to this @dconyard , I’ve done a lot of similar work in other projects so I found this interesting :slight_smile:

Something else you may stumble across in your project - in addition to changing your post link you may also need to consider pagination links if applicable. And alter those to account for your custom rewrites.

Finally there may be some work to do when someone adds multiple taxonomy terms to your custom post and which URL gets precedence as a result, in this instance I hooked into a filter for the taxonomy to only allow one taxonomy term whilst still retaining the taxonomy hierarchy