=== Rich Taxonomy ===

Tags: seo, category, topic cluster, pillar page, landing page  
Contributors: tarosky, Takahashi_Fumiki, megane9988, tswallie  
Requires at least: 6.6  
Tested up to: 7.0  
Requires PHP: 8.1  
Stable Tag: 1.3.0
License: GPLv3 or later  
License URI: http://www.gnu.org/licenses/gpl-3.0.txt

A WordPress plugin that enhances taxonomy archives by replacing them with custom **Taxonomy Pages**.  

== Description ==

> **Note:** This plugin works with both **classic themes** and **block themes** that support Full Site Editing (FSE).

- Replace term archive pages with custom Taxonomy Pages (CPT).
- Use the block editor to design archive landing pages.
- Includes a **Taxonomy Archive Block** to display posts.
- Fully customizable via templates and filter hooks.

= Use Cases =

**Topic clusters & pillar pages (SEO).** Turn a category or tag archive into a *pillar page* that introduces the topic and links out to its individual posts (the *cluster content*). This is the topic-cluster model used in modern SEO: one authoritative hub page that consolidates internal links and signals topical authority — instead of a bare, auto-generated list of post titles.

**Category & taxonomy landing pages.** Give any taxonomy term a fully designed landing page — hero, introduction, curated blocks — while still automatically listing the posts assigned to that term. Ideal for product categories, service areas, or editorial sections.

**Content hubs.** Build a curated hub for a series, event, or campaign: write an editorial introduction in the block editor, then let the Taxonomy Archive Block surface the latest related posts automatically.

= How It Works =

The Taxonomy Page will override the **first page** of a term archive. In **Settings** you can choose which taxonomies should have the option to create a Taxonomy Page.

For example, to create a Taxonomy Page for the *News* category:

1. In **Settings → Reading** select `Category`.
2. Go to **Posts → Categories**, hover over "News" and click **Taxonomy Page**.
3. Edit the Taxonomy Page in the block editor and publish it.
4. View the page at `/category/news` (assuming your permalink structure is set to “Post name”).

= Taxonomy Archive Block =

When editing a Taxonomy Page in the block editor, you also have access to the Taxonomy Archive Block. This block displays an overview of every post in the term archive. A number of options allow you to alter its behavior:

- **Number of Posts**  
Sets the maximum number of posts displayed in the overview.

- **Toggle Button Text**  
Sets the text for the toggle button. This button appears when the total number of posts exceeds the number set in "Number of Posts".

- **Archive Button Text**  
Sets the text for the archive button. This button links to the second page of the term archive. It will be displayed when the amount of posts exceeds `Blog pages show at most` in **Settings → Reading**.

= Template Structure =

You can choose a template for the Taxonomy Page in the block editor. Alternatively, you can create your own template, by adding `singular-taxonomy-page.php` to your theme's templates, or using the filter hook `rich_taxonomy_include_template`.

The default template hierarchy, from highest to lowest priority, is as follows:

1. `singular-taxonomy-page.php`
2. `page.php`
3. `single.php`
4. `singular.php`
5. `index.php`

= Customization =

 Template Override: Taxonomy Archive Block 

To override the layout of the Taxonomy Archive Block, copy these files into your theme under:

<pre>template-parts/rich-taxonomy/</pre>

Files:

- `archive-block-loop.php` - Loop of post list
- `archive-block-more.php` - Archive button
- `archive-block-toggle.php` - Toggle button
- `archive-block-wrapper.php` - Wrapper of archive

 Styles and Scripts 

You can override the plugin’s styles and scripts using these hooks:

1. `rich_taxonomy_block_asset_style`
2. `rich_taxonomy_block_asset_editor_style`
3. `rich_taxonomy_block_asset_script`
4. `rich_taxonomy_block_asset_editor_script`

To change the look & feel, `rich_taxonomy_block_asset_style` is the best starting point.

 Example: Override Style 

<pre>// Register style.
add_action( 'init', function() {
    wp_register_style( 'my-archive-block', $url, $deps, $version );
} );

// Override handle.
add_filter( 'rich_taxonomy_block_asset_style', function( $handle, $block_name ) {
    if ( 'rich-taxonomy/archive-block' === $block_name ) {
        $handle = 'my-archive-block';
    }
    return $handle;
}, 10, 2 );</pre>

> This style will load on both the front-end and block editor.

 Default Contents 

To define the default content of the Taxonomy Page, use the `rich_taxonomy_default_post_object` filter hook.

 Example: Define Default Content 

<pre>/**
 * Filter default post object.
 *
 * @param array   $args    Post object passed to wp_insert_post().
 * @param WP_Term $term    Term object assigned to this post.
 * @param string  $context Currently only 'api' is supported.
 */ 
add_filter( 'rich_taxonomy_default_post_object', function( $args, $term, $context ) {
    // If specific taxonomy, enter default content.
    if ( 'category' === $term-&gt;taxonomy ) {
        // Post body.
        $args['post_content'] = 'Here comes default content.';
        // Publish immediately.
        $args['post_status']  = 'publish';
    }
    return $args;
}, 10, 3 );</pre>

== Installation ==

= From Plugin Directory =

1. Install and activate the plugin.
2. Go to **Settings → Reading** and select the taxonomies to enable.

= From GitHub =

Download from the [Releases page](https://github.com/tarosky/rich-taxonomy/releases).

== FAQ ==

= Where can I get support? =

Please create a new ticket on the support forum.

= How can I contribute? =

Create a new [issue](https://github.com/tarosky/rich-taxonomy/issues) or send [pull requests](https://github.com/tarosky/rich-taxonomy/pulls).

== Screenshots ==

1. Edit a Taxonomy Page in the block editor, including the Taxonomy Archive Block and its settings.
2. The Taxonomy Page shown on the front end in place of the term archive.
3. Create a Taxonomy Page directly from the term list (Posts → Categories).

== Changelog ==

= 1.3.0 =

* Add support for creating a Taxonomy Page for a taxonomy's base URL (the whole archive), in addition to individual terms.
* Raise minimum requirements to PHP 8.1 and WordPress 6.6.
* Confirm compatibility with WordPress 7.0.
* Update the plugin icon.

= 1.2.1 =

* Update Node.js version to 20 in release workflow.

= 1.2.0 =

* Add block theme (FSE) support for template override.
* Fix template override when `single.php` exists in classic themes.
* Fix layout of the sync information notice.
* Replace Gulp build system with npm scripts and `@kunoichi/grab-deps`.

= 1.1.8 =

* Add pagination to the broken page warning.
* Add notices to improve UX.
* Bugfix: handle missing taxonomy and null term.

= 1.1.7 =

* Enhancement for instructions.
* Bugfix: remove warning on non-taxonomy pages.

= 1.1.2 =

* Fix bug on template selector.

= 1.1.1 =

* Fix a bug that breaks the block widgets screen.
* Update README for clearance of installation. props [@megane9988](https://profiles.wordpress.org/megane9988/)

= 1.1.0 =

* Fix the bug for block disappearing.

= 1.0.9 =

* Fix a bug in the template selector in the taxonomy page editor.

= 1.0.0 =

* First release.
