Show a list of first-level product categories on a single category page

by

Summary

A shortcode‑based Gutenberg block that displays top‑level WooCommerce product categories appeared everywhere except on product category archive pages. WooCommerce’s template loading and conditional logic prevented the block from rendering, causing the category list to disappear exactly where the merchant needed it most.

Root Cause

WooCommerce category archive templates apply conditional suppression of top‑level category lists. When viewing a specific product category, WooCommerce assumes the user already navigated into a taxonomy branch and therefore hides global category lists.

Key factors:

  • WooCommerce template hierarchy overrides theme output
  • is_product_category() triggers different rendering logic
  • Some themes or builders wrap category archives with filters that strip shortcodes
  • Gutenberg HTML blocks inside PHP templates do not always execute on taxonomy pages

Why This Happens in Real Systems

  • Template hierarchy conflicts: Category archives use taxonomy-product_cat.php, which may not execute the same hooks as archive-product.php.
  • Conditional logic: WooCommerce hides top‑level categories to avoid “duplicate navigation.”
  • Theme interference: Many themes override WooCommerce templates and unintentionally remove shortcode execution.
  • Block rendering limitations: Gutenberg blocks rendered via do_shortcode() behave differently depending on context.

Real-World Impact

  • Users cannot access global navigation from category pages.
  • Merchants lose cross‑category discovery, reducing conversions.
  • Inconsistent UI frustrates customers and increases bounce rates.
  • Support teams waste time debugging what appears to be a “random disappearance.”

Example or Code (if necessary and relevant)

A minimal fix involves forcing the shortcode to render on category pages by hooking into WooCommerce’s archive output.

add_action( 'woocommerce_before_main_content', function() {
    if ( is_product_category() ) {
        echo do_shortcode('[html_block id="939"]');
    }
});

How Senior Engineers Fix It

  • Bypass WooCommerce’s conditional suppression using hooks like woocommerce_before_main_content or woocommerce_archive_description.
  • Ensure shortcode execution by placing it in a hook that always fires on taxonomy pages.
  • Avoid template overrides that break shortcode rendering.
  • Test across all template contexts (shop, product, category, tag, search).
  • Stabilize the UI by placing navigation in a hook rather than inside theme templates.

Why Juniors Miss It

  • They assume shortcodes behave identically everywhere, unaware of WooCommerce’s template hierarchy.
  • They don’t know WooCommerce intentionally hides top‑level categories on category pages.
  • They rely on theme templates instead of WooCommerce hooks, causing inconsistent rendering.
  • They rarely inspect conditional logic like is_product_category() that changes output behavior.

Leave a Comment