Taxonomy Blocks

Taxonomy Blocks enables block-based content editing for WordPress taxonomy term archives.

Instead of maintaining custom PHP templates for each term, the plugin stores block content in an internal post type and renders that content on taxonomy archive pages.

Overview

The plugin adds a settings screen where administrators can:

• enable supported public taxonomies for block editing
• choose how taxonomy block content is injected on archive pages

Once a taxonomy is enabled, each term gets an Edit with blocks action in the admin. That action opens a connected internal block entry in the WordPress block editor. The saved content is then rendered on the corresponding term archive.

Feature Set

• Block editor support for selected public taxonomies
• Per-term archive content stored independently from theme templates
• Automatic output injection for both classic themes and block themes
• Shortcode support for manual rendering
• Admin settings UI built with React and the WordPress packages

How It Works

Internal content model

The plugin registers an internal post type named tb_block.

Each tb_block post represents the block content for a single taxonomy term. The relationship is stored with post meta:

• term_id
• tax_name

When an editor clicks Edit with blocks for a term, the plugin looks up the related tb_block post. If none exists yet, one is created automatically.

Front-end rendering

Rendering behavior is controlled by the tb_display_method option.

For classic themes, the plugin can inject content:

• before the main content area
• after the main content area
• before the archive loop
• after the archive loop

For block themes, the plugin can inject content:

• before the main content area
• after the main content area
• before the main Query Loop block
• after the main Query Loop block

If you need manual placement, use the shortcode or the PHP helper function.

[taxonomy_blocks]
[taxonomy_blocks term_id="123"]

<?php taxonomy_blocks(); ?>
<?php taxonomy_blocks( 123 ); ?>

Settings

The plugin stores two WordPress options:

• tb_taxonomies: enabled taxonomy slugs
• tb_display_method: selected output strategy

These settings are registered with register_setting() and exposed through the WordPress REST API. The admin application reads and updates them through /wp/v2/settings.

Plugin Structure

taxonomy-blocks/
├── taxonomy-blocks.php
├── inc/
│   ├── setup.php
│   ├── class-tb-admin-menu.php
│   ├── class-tb-app-assets.php
│   ├── class-tb-database-options.php
│   ├── class-tb-helper.php
│   ├── class-tb-injection-methods.php
│   ├── class-tb-post-type.php
│   ├── class-tb-post-type-hooks.php
│   ├── class-tb-shortcodes.php
│   ├── class-tb-taxonomy-admin-screen.php
│   └── class-tb-taxonomy-hooks.php
├── src/
│   ├── admin-options/
│   └── post-type-options/
└── build/
    ├── admin-options/
    └── post-type-options/

Main Components

Bootstrap

taxonomy-blocks.php defines plugin constants and loads the plugin setup file.

Admin settings UI

The settings screen is registered under Settings > Taxonomy Blocks.

The UI is rendered by the JavaScript app in src/admin-options/ and compiled into build/admin-options/.

Taxonomy term integration

The plugin adds an Edit with blocks action to enabled taxonomies. This is implemented in the taxonomy admin screen integration class and is protected with capability checks and nonces.

Output injection

Automatic front-end placement is handled by the injection methods class. Depending on the selected mode, the plugin uses WordPress actions, filters, and output buffering to prepend or append saved block content to archive output.

Shortcode

The plugin registers a shortcode for manual rendering:

[taxonomy_blocks]

When no term_id is provided, the current queried term is used.

Template function

The plugin also exposes a PHP helper function for theme or template usage:

<?php taxonomy_blocks(); ?>
<?php taxonomy_blocks( 123 ); ?>

Use this function when you want to render taxonomy block content directly in a PHP template, theme override, or custom integration.

When no term ID is passed, the function uses the currently queried term.

Development

Requirements

• PHP 7.4+
• WordPress 6.8+
• Node.js and npm

Install dependencies

npm install

Available scripts

npm run start
npm run build
npm run lint:js
npm run lint:css
npm run format
npm run plugin-zip

Build process

Source files live in src/ and are compiled into build/ using @wordpress/scripts.

For production releases, the compiled assets in build/ must be included.

Extension Notes

The plugin currently exposes one front-end customization filter:

tb_taxonomy_blocks_wrapper_classes

This filter lets you change the CSS classes applied to the wrapper element around rendered taxonomy block content.

By default, the plugin outputs a wrapper like this:

<div class="taxonomy-blocks tb-term-slug-example tb-term-id-123 tb-tax-name-category">

The filter receives three arguments:

• the default wrapper class string
• the current WP_Term object
• the internal tb_block post ID used to render the content

This makes it useful when you want to:

• add project-specific utility classes
• target specific taxonomies or terms
• attach classes expected by a theme or CSS framework
• add per-term identifiers for styling or JavaScript hooks

Example:

add_filter(
    'tb_taxonomy_blocks_wrapper_classes',
    function ( $classes, $term, $post_id ) {
        if ( ! $term instanceof WP_Term ) {
            return $classes;
        }

        $classes .= ' archive-intro';
        $classes .= ' archive-intro--' . sanitize_html_class( $term->taxonomy );
        $classes .= ' archive-intro--term-' . absint( $term->term_id );

        if ( 0 !== $post_id ) {
            $classes .= ' archive-intro--source-' . absint( $post_id );
        }

        return $classes;
    },
    10,
    3
);

The filter changes wrapper classes only. It does not alter the block content itself.

Operational Notes

• The internal tb_block post type is not public.
• The post type is available in the REST API so the block editor can be used.
• The plugin caches the relationship between terms and internal block posts with transients.
• When a taxonomy term is deleted, associated plugin content is cleaned up through taxonomy hooks.

Intended Use

Taxonomy Blocks is useful when you need reusable, editor-managed content on taxonomy archives such as:

• category archive intros
• custom taxonomy landing content
• tag archive hero sections
• archive-specific calls to action

License

GPL-2.0-or-later