Taxonomy extensibility: document it, and register Topics by post type support

[mauteri]

Two related pieces of work that came out of #1115, where @audunmb asked for more taxonomy flexibility. Most of what was requested is already possible; it just isn't written down, and one piece doesn't behave the way the 0.34.0 abstraction implies it should.

1. Document taxonomy extensibility

@mauteri committed to this on #1115 in July 2025. There's already a home for it alongside docs/developer/post-type-supports/README.md and docs/developer/theme-customizations/README.md.

The doc should cover:

• Adding your own taxonomy to events. Standard register_taxonomy() against the event post type, or register_taxonomy_for_object_type() for one that already exists. Worth showing the get_post_types_by_support( 'gatherpress-event-date' ) pattern so it works for custom event post types too, not just gatherpress_event.
• Attaching core categories and tags to events (Add more flexibility for taxonomies #1115 item 5).
• Removing Topics for sites that don't want them.
• Renaming Topics, e.g. "Genre" for a music venue (Add more flexibility for taxonomies #1115 item 3). This already works via WordPress core's taxonomy_labels_gatherpress_topic filter, and it's worth documenting that GatherPress goes further: Topic::get_localized_taxonomy_slug() reads the filtered singular name back and derives the URL slug from it, with locale switching. So a rename changes both the labels and the permalink.
• Hierarchical vs flat, and when each makes sense. @audunmb's example was Performer wanting to be flat while Genre wants hierarchy.
• A pointer to add-on territory for things that shouldn't live in core, e.g. @carstingaxion's gatherpress-taxonomy-colors for Add more flexibility for taxonomies #1115 item 6.

Out of scope here: Organizer as a taxonomy (#1115 item 2), which is its own conversation in discussion #1638.

2. Register the Topic taxonomy by post type support, not by post type

Topic::register_taxonomy() hardcodes the post type:

register_taxonomy(
	self::TAXONOMY,
	Event::POST_TYPE,
	array(

includes/core/classes/class-topic.php:78

AGENTS.md's own rule for the 0.34.0 abstraction is to use get_post_types_by_support( 'gatherpress-event-date' ) rather than hardcoded post type slugs. As written, a custom post type declaring gatherpress-event-date gets datetime handling, RSVPs, venues, and calendar feeds, but silently no Topics. That's inconsistent with every other event feature and reads as a bug to anyone building on the supports.

Changing it also makes the documentation in part 1 honest, since the "add your own taxonomy across all event-supporting post types" guidance would otherwise be advice core itself doesn't follow.

Worth checking while in there whether anything else assumes Topics are gatherpress_event-only, and whether registration needs to move to a later init priority so support declarations from other plugins are already in place (AGENTS.md notes priority 11 for this pattern).

[carstingaxion]

Renaming Topics, e.g. "Genre" for a music venue (Add more flexibility for taxonomies #1115 item 3). This already works via WordPress core's taxonomy_labels_gatherpress_topic filter, and it's worth documenting that GatherPress goes further: Topic::get_localized_taxonomy_slug() reads the filtered singular name back and derives the URL slug from it, with locale switching. So a rename changes both the labels and the permalink.

Already done, testable in "Happenings at Spots" Playground, where "Topics" became "Types".

https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/carstingaxion/gatherpress-demos/main/happenings-at-spots/blueprint.json