This guide covers the taxonomy system used to organize documentation in DocSync.

For API endpoint details, see the API Reference.

Overview

DocSync uses two taxonomies to organize documentation:

• project taxonomy: Hierarchical system for organizing documentation by project structure
• project_type taxonomy: Non-hierarchical system for categorizing project types

Project Type Taxonomy

The project_type taxonomy provides non-hierarchical categorization of projects:

Project Type Taxonomy

The project_type taxonomy provides non-hierarchical categorization of projects by type. Project types are created dynamically as needed and stored as term meta on project terms.

Managing Project Types

Project types are stored as term meta on project terms (depth 0 in the project taxonomy). Use the Project API to set project types:

# Set project type for a project term
curl -X PUT /wp-json/docsync/v1/project/{project_term_id} 
  -H "Content-Type: application/json" 
  -d '{
    "meta": {
      "project_type": "wordpress-plugins"
    }
  }'

Project Type in REST API

The docs endpoint includes project type information:

{
  "id": 123,
  "title": "My Plugin Docs",
  "project_type": "wordpress-plugins",
    "project_path": ["my-plugin", "api"]
}

Managing Taxonomy Terms

Managing Terms via API

The REST API does not provide an endpoint to create arbitrary project terms directly (there is no POST /project). Use POST /project/resolve with create_missing: true to create missing segments in a path.

Path Resolution

Automatically create hierarchical paths:

curl -X POST /wp-json/docsync/v1/project/resolve 
  -H "Content-Type: application/json" 
  -d '{
    "path": ["my-plugin", "api", "endpoints"],
    "create_missing": true,
    "project_meta": {
      "github_url": "https://github.com/user/my-plugin",
      "wp_url": "https://wordpress.org/plugins/my-plugin"
    }
  }'

This creates all missing terms in the hierarchy. The first segment ("my-plugin") becomes a project term at depth 0.

Permissions note: POST /project/resolve is public when create_missing is false, and requires manage_categories when create_missing is true.

Updating Terms

curl -X PUT /wp-json/docsync/v1/project/{term_id} 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Updated Plugin Name",
    "description": "New description",
    "meta": {
      "github_url": "https://github.com/user/repo",
      "wp_url": "https://wordpress.org/plugins/repo"
    }
  }'

PUT /project/{id} only updates name, description, meta.github_url, and meta.wp_url.

Listing Terms

# Get all terms
curl /wp-json/docsync/v1/project

# Get hierarchical tree
curl /wp-json/docsync/v1/project/tree

# Filter by parent
curl /wp-json/docsync/v1/project?parent=5

# Hide empty terms
curl "/wp-json/docsync/v1/project?hide_empty=true"

Repository Metadata

Repository Metadata

PUT /project/{id} only updates name, description, meta.github_url, and meta.wp_url.

• meta.github_url is stored as project_github_url
• meta.wp_url is stored as project_wp_url

PUT /project/{id} only updates name, description, meta.github_url, and meta.wp_url.

• meta.installs
• repository_info (the computed repository info array returned by chubes_get_repository_info())

Automatic Fetching

The term update endpoint supports setting two URLs:

• WordPress.org API: Install counts, ratings, last updated
• GitHub API: Stars, forks, description, language

Manual Metadata Updates

The term detail endpoint (GET /project/{id}) also returns:

• meta.github_url → project_github_url
• meta.wp_url → project_wp_url

curl -X PUT /wp-json/docsync/v1/project/{project_term_id} 
  -H "Content-Type: application/json" 
  -d '{
    "meta": {
      "github_url": "https://github.com/user/repo",
      "wp_url": "https://wordpress.org/plugins/repo"
    }
  }'

Integration with Documentation

Assigning Taxonomy to Posts

The plugin automatically fetches metadata from APIs:

curl -X POST /wp-json/docsync/v1/docs 
  -H "Content-Type: application/json" 
  -d '{
    "title": "API Documentation",
    "content": "# API Docs...",
  "project_path": ["my-plugin", "api"]
  }'

PUT /wp-json/docsync/v1/project/{id} only persists:

Sync System Integration

When creating documentation via API:

curl -X POST /wp-json/docsync/v1/sync/doc 
  -H "Content-Type: application/json" 
  -d '{
    "title": "Installation Guide",
    "content": "# Installation...",
    "project_term_id": 123,
    "filesize": 2048,
    "timestamp": "2025-12-01T10:00:00Z",
    "subpath": ["guides", "installation"]
  }'

URL Structure

Taxonomy URLs

The project_path parameter automatically resolves to the appropriate taxonomy terms. The first segment creates or finds a project term at depth 0.

• /project/my-plugin/ – Project archive
• /project/my-plugin/api/ – Subpath archive
• /project/my-plugin/api/endpoints/ – Deeper subpath archive

Documentation URLs

The sync system uses taxonomy paths for organization:

• /docs/my-plugin/readme/ – Project README
• /docs/my-plugin/api/endpoints/ – API docs

Admin Interface

Repository Fields

Terms generate URLs following the pattern:

• GitHub URL: Repository link
• WordPress.org URL: Plugin/theme directory link
• Version: Current version string
• Install Count: Display of active installs (read-only, auto-updated)

Install Tracking

Documentation posts use hierarchical URLs:

• Fetches install counts from WordPress.org API
• Updates term metadata daily
• Displays statistics in admin interface
• Provides trending data

Best Practices

Naming Conventions

• Use lowercase slugs with hyphens: my-wordpress-plugin
• Use descriptive project names: advanced-custom-fields, not acf

Hierarchy Organization

• Project Terms: One term per repository at depth 0
• Subpaths: Logical content organization within projects
  • Use descriptive subdirectory names that match your content structure

Metadata Management

• Use descriptive subdirectory names that match your content structure

Performance Considerations

• Use descriptive subdirectory names that match your content structure

Troubleshooting

Common Issues

The admin interface provides meta boxes for:

• Always include repository URLs for auto-fetching
• Keep version numbers current
• Use consistent metadata field names
• Regularly update project information

The InstallTracker class automatically:

• Limit deep hierarchies (max 4-5 levels)
• Use hide_empty=1 for display queries
• Cache taxonomy queries when possible
• Batch taxonomy operations

"Term not found"

• Check slug spelling and case sensitivity
• Verify term exists with GET /project/{id}

Debug Queries

"Path resolution failed"

// In wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

// Check debug.log for taxonomy operations

Cleanup Operations

"Metadata not updating"

# Find empty terms
curl /wp-json/docsync/v1/project?hide_empty=0

# Manual cleanup (use WordPress admin or custom script)

Advanced Usage

Custom Metadata Fields

Enable taxonomy debugging:

// Via PHP
update_term_meta($term_id, 'custom_field', 'value');

// Via API
curl -X PUT /wp-json/docsync/v1/project/{id} 
  -d '{"meta": {"custom_field": "value"}}'

Taxonomy Queries

Remove unused terms:

$args = array(
  'taxonomy' => 'project',
  'parent' => 0, // Top level only
  'hide_empty' => false,
  'meta_query' => array(
    array(
      'key' => 'github_url',
      'value' => 'github.com',
      'compare' => 'LIKE'
    )
  )
);
$terms = get_terms($args);

Bulk Operations

Add custom fields to taxonomy terms:

# Get all project terms
curl /wp-json/docsync/v1/project?hide_empty=0

# Batch update metadata
# (Implement custom endpoint or use multiple PUT requests)