Working with Wiki Extension

The Wiki extension (t2/wiki) provides a complete knowledge base / documentation system for WordPress. It registers a custom post type for wiki articles with hierarchical topics, search functionality, and specialized blocks for navigation and discovery.

link For End Users

link What Does This Extension Do?

The Wiki extension allows you to:

Create structured documentation with wiki articles and hierarchical topics
Search wiki content with a dedicated search block
Navigate topic hierarchies with automatic topic trees
Display related articles organized by topics
Enable table of contents for long-form articles
Customize article layouts with sidebar support for navigation

link Features Available

link Post Type: Wiki Article

Custom post type for knowledge base articles
Full block editor support for rich content
Featured images and excerpts
Hierarchical topic taxonomy for organization

link Taxonomy: Topics

Hierarchical taxonomy for organizing articles
Nested topic structure (topics and subtopics)
Topic-based article filtering and display

link Article Features

Table of Contents: Automatic TOC generation for articles
Topic Tree: Sidebar navigation showing topic hierarchy
Related Articles: Automatic article suggestions per topic

link Custom Blocks

Wiki Search (t2/wiki-search): Dedicated search interface for wiki articles
Wiki Topics (t2/wiki-topics): Display topic lists with article counts and navigation

link How to Use

Enable the Extension
- Go to WordPress Admin → T2 Settings
- Enable the "Wiki" extension
- Important: Also enable dependencies:
  - t2/enable-generate-anchors (for TOC support)
  - t2/table-of-contents (for TOC block)
- Or add to your theme's t2.json:
```
{
  "mu-extensions": [
    "t2/wiki",
    "t2/enable-generate-anchors",
    "t2/table-of-contents"
  ]
}
```
Create Topics
- Navigate to "Wiki" → "Topics" in WordPress admin
- Create parent topics (e.g., "Getting Started", "Advanced")
- Create child topics under parents for nested structure
- Topics can have descriptions and custom slugs
Create Wiki Articles
- Go to "Wiki" → "All articles"
- Click "New article"
- Write your article content using the block editor
- Assign one or more topics
- Add featured image and excerpt (optional)
- Configure article settings in the sidebar:
  - Enable/disable Table of Contents
  - Enable/disable Topic Tree in sidebar
Add Search to Your Site
- Edit any page where you want wiki search
- Add the Wiki Search block
- Configure initial articles display:
  - Empty: Show search box only
  - Latest: Display recent articles
  - Manual: Choose specific articles to show
- Customize search placeholder and styling
Display Topics
- Add the Wiki Topics block to any page
- Choose display mode:
  - All topics
  - Manual selection of specific topics
  - Subtopics of a parent topic
- Configure articles per topic limit
- Show/hide article counters

link Best Practices

Use hierarchical topics for better organization (e.g., "API" → "Authentication", "API" → "Endpoints")
Enable TOC for long articles to improve navigation
Keep topic trees shallow (2-3 levels) for better UX
Use featured images for visual consistency in search results
Write clear excerpts that appear in search and topic listings

link For Developers

link Architecture

link File Structure

packages/extension-library/src/wiki/
├── block-library/
│   ├── wiki-search/          # Search interface block
│   │   ├── block.json
│   │   ├── block.php
│   │   ├── editor.js
│   │   ├── view.js           # Frontend search functionality
│   │   └── style.css
│   └── wiki-topics/          # Topics display block
│       ├── block.json
│       ├── block.php
│       ├── editor.js
│       └── style.css
├── inc/
│   ├── api/                  # REST API endpoints
│   ├── assets.php            # Asset enqueueing
│   ├── config.php            # Configuration helpers
│   ├── helpers.php           # Utility functions
│   ├── rest-api.php          # REST API registration
│   ├── schema.php            # Post type & taxonomy registration
│   └── templating.php        # Featured content templates
├── templates/                # PHP templates for rendering
├── src/                      # Source files (if applicable)
├── extension.json            # Extension metadata
├── extension.php             # Entry point
├── constants.js              # JS constants
├── index.js                  # Frontend JS initialization
├── view.js                   # Frontend interactions
├── style.css                 # Frontend styles
├── style-sidebar.css         # Sidebar-specific styles
└── props.css                 # Additional property styles

link Key Components

REST API (inc/rest-api.php, inc/api/)

Custom endpoints for wiki-specific queries
Search functionality
Topic tree data
Article filtering by topics

Schema Registration (inc/schema.php)

Wiki post type registration
Topic taxonomy registration
Post meta registration (TOC, topic tree toggles)
Transient caching for topic trees

Templating (inc/templating.php, templates/)

Featured Content card templates
Custom rendering for wiki articles

link Configuration Options

Configure via t2.json in your theme root:

{
  "version": 1,
  "mu-extensions": [
    "t2/wiki",
    "t2/enable-generate-anchors",
    "t2/table-of-contents"
  ],
  "t2/wiki": {
    "postTypeKey": "wiki",
    "taxonomyTopicKey": "topic",
    "features": {
      "toc": true,
      "topicTree": true
    }
  }
}

link Configuration Reference

Key	Type	Default	Description
`postTypeKey`	string	`"wiki"`	Custom post type slug for wiki articles
`taxonomyTopicKey`	string	`"topic"`	Taxonomy slug for topics
`features.toc`	boolean	`true`	Enable table of contents meta field
`features.topicTree`	boolean	`true`	Enable topic tree meta field

link Post Meta Keys

The extension registers the following post meta fields:

enable_toc (boolean, default: true): Whether to display table of contents for this article
enable_topic_tree (boolean, default: true): Whether to display topic tree sidebar for this article

Both fields are:

Exposed via REST API (show_in_rest: true)
Available in the block editor sidebar
Accessible on the post object after the_post hook

link Enhanced WP_Post Object

The wiki extension enhances WP_Post objects with additional properties:

// After the_post() hook, wiki posts have:
$post->display_toc        // boolean: TOC enabled?
$post->display_topic_tree // boolean: Topic tree enabled?

This allows easy access in templates:

if ( $post->display_topic_tree ) {
    // Render topic tree sidebar
}

link Topic Tree System

Caching Strategy

Topic trees are cached in transients (1 hour TTL)
Cache invalidated on topic create/update/delete
Two cache variants: with and without empty topics

Helper Functions (inc/schema.php)

// Get the full topic tree
$tree = \T2\Extensions\Library\Wiki\Schema\get_topic_tree(
    $with_empty_topics = false,
    $no_cache = false
);

// Each tree item contains:
// - term_id, name, slug, description, count
// - children (array of child topic items)

link REST API

The extension provides custom REST API endpoints under t2/wiki/v1 namespace:

Constants

T2_EXTENSIONS_WIKI_REST_API_PREFIX = 't2/wiki/v1'

See inc/rest-api.php and inc/api/ for endpoint implementations.

link Block: Wiki Search

Block Name: t2/wiki-search

Attributes:

{
  "initialArticlesList": "empty|latest|manual",
  "maxNumberOfInitialArticles": 9,
  "manualArticles": [],
  "displayInitialArticlesTitle": true,
  "initialArticlesTitle": "Latest articles"
}

Frontend Behavior (view.js):

Real-time search using REST API
Debounced search input
Results rendered with JS
Accessible keyboard navigation

link Block: Wiki Topics

Block Name: t2/wiki-topics

Attributes:

{
  "selection": "all|manual|subtopics",
  "manualTopics": [],
  "subtopicsOf": 0,
  "articlesPerTopic": 10,
  "maxNumberOfTopics": 50,
  "hideArticlesCounter": false,
  "showSubtopicsOnly": false
}

Rendering:

Server-side rendering in PHP
Displays topic hierarchies with article lists
Shows article counts per topic
Supports nested topic display

link Helper Functions

get_wiki_post_type() (inc/config.php)
Returns the configured wiki post type key:

use function T2\Extensions\Library\Wiki\Config\get_wiki_post_type;

$post_type = get_wiki_post_type(); // 'wiki' by default

get_topic_taxonomy() (inc/config.php)
Returns the configured topic taxonomy key:

use function T2\Extensions\Library\Wiki\Config\get_topic_taxonomy;

$taxonomy = get_topic_taxonomy(); // 'topic' by default

get_taxonomy_terms_tree() (inc/helpers.php)
Build a hierarchical tree of taxonomy terms:

use function T2\Extensions\Library\Wiki\Helpers\get_taxonomy_terms_tree;

$tree = get_taxonomy_terms_tree(
    $taxonomy = 'topic',
    $parent_id = 0,
    $with_empty = false
);

link Featured Content Integration

The wiki extension automatically registers a card template for Featured Content Layout block:

register_featured_content_template(
    "post-type-{$wiki_post_type}",
    get_wiki_card_template()
);

This provides styled cards when displaying wiki articles in Featured Content blocks.

link Extension Dependencies

Required Extensions (must be enabled):

t2/enable-generate-anchors: Generates anchor IDs for headings (required for TOC)
t2/table-of-contents: Provides TOC block functionality

These dependencies are declared in extension.json:

{
  "extensionDependencies": [
    "t2/enable-generate-anchors",
    "t2/table-of-contents"
  ]
}

link Constants Defined

T2_EXTENSIONS_WIKI_PATH               // Path to wiki extension directory
T2_EXTENSIONS_WIKI_TEMPLATES_PATH     // Path to templates subdirectory
T2_EXTENSIONS_WIKI_REST_API_PREFIX    // REST API namespace (t2/wiki/v1)

link Development Tips

Build required for JS changes: Run npm run build after editing view.js or editor files
Transient cache: Clear transients during development: wp transient delete --all
REST API testing: Use wp-json/t2/wiki/v1/ endpoints for API testing
Topic tree performance: Large topic hierarchies benefit from caching; monitor transient usage
Search customization: Modify view.js for frontend search behavior

link Hooks & Actions

Actions

init - Registers post type, taxonomies, and meta fields
the_post - Enhances WP_Post objects with wiki-specific properties
created_{$topic_taxonomy} - Clears topic tree cache
edited_{$topic_taxonomy} - Clears topic tree cache
delete_{$topic_taxonomy} - Clears topic tree cache

link Common Use Cases

Custom Search Results Template
Modify the search results rendering by editing templates in templates/ directory.

Add Custom Post Meta

add_action( 'init', function() {
    register_post_meta( 'wiki', 'custom_field', [
        'type'         => 'string',
        'single'       => true,
        'show_in_rest' => true,
    ] );
}, 11 ); // After wiki registers its post type

Customize Topic Display
Filter topic queries before rendering in the Wiki Topics block.

Extend REST API
Add custom endpoints under T2_EXTENSIONS_WIKI_REST_API_PREFIX namespace:

add_action( 'rest_api_init', function() {
    register_rest_route( T2_EXTENSIONS_WIKI_REST_API_PREFIX, '/custom-endpoint', [
        'methods'  => 'GET',
        'callback' => 'your_callback_function',
    ] );
} );

link Performance Considerations

Topic Tree Caching: Trees are cached for 1 hour; large hierarchies benefit significantly
Search Queries: Frontend search uses REST API; consider pagination for large article sets
Transient Cleanup: Topic tree transients auto-expire but can be manually cleared
Featured Content: Wiki cards use the same optimization as other Featured Content blocks

link Known Limitations

Search is client-side only (no server-side fallback)
Topic tree depth is not limited programmatically (UX recommendation: 3 levels max)
TOC requires Generate Anchors extension to be enabled
No built-in article versioning or revision comparison

link Testing

E2E Tests: See tests/e2e/ for Playwright tests covering:

Article creation
Topic assignment
Search functionality
Block rendering

Unit Tests: PHP unit tests for:

Topic tree building
Post meta registration
REST API endpoints