Place single entries below taxonomy terms

A POM custom post type can inherit the public archive path of one connected taxonomy. An assigned entry then sits directly below its selected term:

/docs-category/pom/first-steps/
/docs-category/pom/first-steps/install-the-theme/

The first route is a term archive. The second is the single entry.

Prepare an eligible taxonomy

Under Settings → POM Theme → Content model:

1. Create and save the custom post type.
2. Create a taxonomy and include that post type under Enabled post types.
3. Leave Disable archive for this taxonomy inactive.
4. Enable Enable hierarchical URLs.
5. Create representative parent and child terms and assign them to a published entry.

The taxonomy must remain public, hierarchical, and connected to the post type for the permalink choice to remain available.

Enable the nested permalink

1. Open Settings → Permalinks.
2. Find Custom post type URLs and the required content type.
3. Under Single entry URL, choose Taxonomy-based.
4. Under URL taxonomy, select the taxonomy that should own the single-entry path.
5. Save the permalink settings.
6. Open an assigned entry and its selected term archive.

Default (custom slug base) preserves the ordinary custom post type URL. If the taxonomy also has a page-backed archive base, the single-entry URL inherits that page path automatically.

How POM chooses the path

• An entry with one assigned term uses that term’s complete archive path.
• An entry with multiple terms uses the deepest assigned term.
• If assigned terms have equal depth, the term with the lowest term ID is used.
• An entry with no assigned term keeps its normal custom post type URL.
• A term archive wins if a term and entry would otherwise occupy the same path.

Only one custom post type can inherit a taxonomy or an equivalent taxonomy archive base. This prevents identical entry slugs from producing ambiguous routes.

The taxonomy-based URL becomes the permalink returned by WordPress. Canonicals, sitemaps, previews, schema, and integrations that use the standard permalink API therefore receive it. An explicit canonical override in an SEO plugin remains controlled by that plugin.

Redirects, routes, and breadcrumbs

The original custom post type route remains available as a permanent redirect to the taxonomy-based canonical URL. A previous nested route can also redirect while its term path still identifies the entry. Pagination, feeds, embeds, comment pages, and translated routes remain separate from single-entry routing.

On the single entry, POM Theme breadcrumbs use any configured page-base ancestors followed by the complete term trail. Rank Math breadcrumbs and breadcrumb schema use the same hierarchy. POM Translate-localized page, taxonomy, term, entry, and language slugs flow through the resulting links.

When Polylang uses language directories, save Settings → Permalinks after enabling it or changing its URL mode.

Choose another assigned term programmatically

Developers can override the default term with pom_taxonomy_permalink_term:

add_filter(
    'pom_taxonomy_permalink_term',
    static function (WP_Term $term, array $terms, WP_Post $post, string $taxonomy): WP_Term {
        return $term;
    },
    10,
    4
);

Return a term that belongs to the configured taxonomy and is already assigned to the entry. Invalid values fall back to POM Theme’s default choice.

The breadcrumb trail can be adjusted with pom_taxonomy_permalink_breadcrumb_terms. Return assigned WP_Term objects in root-to-leaf order.

Verify and disable

Test an entry with one term, several terms, and no term. Confirm its canonical URL, old-route redirect, term archive, breadcrumb trail, sitemap entry, and each active language.

To disable the structure, select Default (custom slug base) under Single entry URL and save Settings → Permalinks. Review external links and caches before changing the taxonomy on a live site.

For page-backed, base-free, and general archive choices, see Configure custom post type URLs.