MagePeople Documentation Hub

A professional, AI-powered documentation system for WordPress with Clerk.io-style design, SEO optimization, and intelligent search capabilities.

Features

🎨 Design & UX

• Clerk.io-Inspired Design: Modern, clean documentation interface with professional aesthetics
• Responsive Layout: Works perfectly on desktop, tablet, and mobile devices
• Dark Mode Ready: CSS variables for easy theme customization
• Syntax Highlighting: Built-in code block highlighting with Highlight.js

🔍 Search & Discovery

• Real-Time Search: Cmd+K keyboard shortcut for instant search
• Advanced Filtering: Filter by category, version, and content
• Sidebar Navigation: Hierarchical category navigation
• Table of Contents: Auto-generated on-page navigation
• Breadcrumb Navigation: Clear navigation path for users

🤖 AI Features

• AI-Powered Chat: Integration with Claude (Anthropic) and OpenAI
• Intelligent Q&A: AI responds based on your documentation context
• RAG Architecture: Retrieves relevant documentation for contextual answers
• Flexible Provider: Switch between OpenAI GPT-4 or Claude 3 Sonnet

📊 SEO Optimization

• Structured Data: Schema.org markup for search engines
• Open Graph Tags: Social media preview optimization
• Twitter Cards: Enhanced Twitter sharing
• XML Sitemap: Auto-generated sitemap for search engines
• Meta Management: Custom meta titles and descriptions
• Breadcrumb Schema: Rich breadcrumb markup

📈 Analytics

• Page View Tracking: Monitor documentation engagement
• Search Analytics: Track what users search for
• Performance Metrics: Identify popular and neglected docs
• Version Tracking: Monitor doc views by version

🔧 Developer-Friendly

• REST API: Full WordPress REST API support
• Gutenberg Editor: Native WordPress block editor support
• Custom Post Type: Dedicated mp_documentation post type
• Taxonomies: Category and version organization
• Hooks & Filters: Extensive customization hooks

Installation

1. Upload Plugin

# Clone or download the plugin
wp plugin install magepeople-docs --activate

# Or upload manually to /wp-content/plugins/

2. Activate Plugin

• Go to WordPress Admin → Plugins
• Find "MagePeople Documentation Hub"
• Click "Activate"

3. Create Documentation Structure

1. Go to Docs Hub → Add New in the WordPress admin
2. Create your first documentation article
3. Assign it to a category
4. Publish

4. Configure Settings

Go to Docs Hub → Settings

General Settings

• Site Name: Display name for your documentation (default: "MagePeople")

AI Configuration

• AI Provider: Choose between OpenAI, Anthropic Claude, or Disabled
• OpenAI API Key: Get from https://platform.openai.com/api-keys
• Anthropic API Key: Get from https://console.anthropic.com

Design & Branding

• Primary Color: Main brand color (default: #1F2937)
• Secondary Color: Accent color (default: #10B981)

Configuration Guide

Setting Up OpenAI

1. Get API Key

   • Visit https://platform.openai.com/api-keys
   • Create a new secret key
   • Copy the key

2. Add to Plugin Settings

   • Go to Docs Hub → Settings
   • Select "OpenAI" as AI Provider
   • Paste your API key in "OpenAI API Key" field
   • Click "Save Settings"

3. Model Configuration

   • The plugin uses gpt-4-turbo-preview by default
   • Requires paid OpenAI account

Setting Up Anthropic Claude

1. Get API Key

   • Visit https://console.anthropic.com
   • Navigate to API Keys
   • Create new API key
   • Copy the key

2. Add to Plugin Settings

   • Go to Docs Hub → Settings
   • Select "Anthropic Claude" as AI Provider
   • Paste your API key in "Anthropic API Key" field
   • Click "Save Settings"

3. Model Configuration

   • The plugin uses claude-3-sonnet-20240229 by default
   • Suitable for most documentation use cases

Customizing Colors

The plugin uses CSS variables for easy customization:

:root {
  --mp-primary: #1F2937;        /* Primary color */
  --mp-secondary: #10B981;      /* Secondary/accent color */
  --mp-dark: #111827;           /* Dark backgrounds */
  --mp-light: #F9FAFB;          /* Light backgrounds */
  --mp-border: #E5E7EB;         /* Border color */
  --mp-text: #374151;           /* Primary text */
  --mp-text-light: #6B7280;     /* Secondary text */
  --mp-text-lighter: #9CA3AF;   /* Tertiary text */
}

To customize, add to your theme's CSS:

:root {
  --mp-primary: #your-color;
  --mp-secondary: #your-accent;
}

Usage Guide

Creating Documentation

Basic Article

1. Go to Docs Hub → Add New
2. Enter title and content
3. Assign category
4. Set version (optional)
5. Publish

SEO Optimization

1. Scroll to Documentation SEO meta box
2. Set custom SEO title
3. Write compelling meta description
4. Add keywords
5. Upload og:image
6. Publish

Content Tips

• Use Headers: Properly structure with H2/H3 headers
• Code Blocks: Wrap code in ``` markers
• Links: Cross-link related documentation
• Excerpts: Always add excerpt for better previews

Organizing with Categories

1. Go to Docs Hub → Categories
2. Click Add New Category
3. Enter category name and description
4. Set display order
5. Add category color/icon
6. Publish

Version Management

1. Go to Docs Hub → Versions
2. Create version numbers (e.g., 1.0, 1.1, 2.0)
3. Mark as current version
4. Assign docs to versions

Using Search

For Users

• Press Cmd+K (Mac) or Ctrl+K (Windows/Linux)
• Type your query
• Click result or press Enter
• Press ESC to close

Sidebar Search

• Use sidebar search box for quick filtering
• Filters categories in real-time

AI Chat Features

Enabling AI Chat

1. Go to Settings
2. Configure AI provider (OpenAI or Anthropic)
3. Save settings
4. Chat widget appears on docs pages

Using AI Chat

• Click Ask AI button in bottom-right
• Type your question
• AI responds based on documentation context
• Supports multiple questions in conversation

Database Schema

Tables Created

mp_docs

• id - Unique document ID
• post_id - WordPress post ID
• slug - URL-friendly slug
• title - Document title
• content - Document content
• category_id - Category reference
• version - Version number
• order_index - Sort order
• seo_title, seo_description, seo_keywords - SEO metadata

mp_docs_categories

• id - Category ID
• name - Category name
• slug - URL slug
• description - Category description
• order_index - Sort order
• icon - Category icon
• color - Display color

mp_docs_versions

• id - Version ID
• version - Version number (e.g., "1.0.0")
• label - Display label
• release_date - Release date
• is_current - Mark as current version

mp_docs_ai_index

• id - Index ID
• doc_id - Document reference
• section_title - Section title
• section_content - Section content
• embeddings - Embedding vector
• tokens - Token count

mp_docs_usage

• id - Record ID
• doc_id - Document reference
• page_views - View count
• search_impressions - Search impressions
• ai_queries - AI queries
• unique_visitors - Unique visitor count
• date - Date of stats

REST API

Get All Documentation

GET /wp-json/wp/v2/documentation

Get Single Documentation

GET /wp-json/wp/v2/documentation/{id}

Search Documentation

POST /wp-json/mp-docs/v1/search
{
  "q": "search query",
  "category": 1,
  "version": "1.0"
}

AI Query

POST /wp-json/mp-docs/v1/ai-query
{
  "question": "How do I...",
  "doc_id": 123
}

Hooks & Filters

Filters

mp_docs_search_results

apply_filters('mp_docs_search_results', $results, $query);

mp_docs_ai_context

apply_filters('mp_docs_ai_context', $context, $question, $doc_id);

mp_docs_seo_title

apply_filters('mp_docs_seo_title', $title, $post_id);

Actions

mp_docs_before_render

do_action('mp_docs_before_render', $post_id);

mp_docs_after_render

do_action('mp_docs_after_render', $post_id);

Troubleshooting

Search Not Working

1. Check if nonce is properly set
2. Verify AJAX URL is correct
3. Check browser console for errors
4. Ensure database tables were created

AI Chat Not Responding

1. Verify API key in settings
2. Check API provider is selected
3. Verify API quota/credits
4. Check server logs for errors

Content Not Displaying

1. Ensure post type is enabled
2. Check post status (must be published)
3. Verify category is assigned
4. Clear WordPress cache

SEO Issues

1. Verify permalinks are enabled
2. Check robots.txt allows /docs
3. Ensure XML sitemap is accessible at /mp-docs-sitemap.xml
4. Submit sitemap to Google Search Console

Performance Optimization

Caching

// Enable query caching
define('WP_CACHE', true);

// Cache documentation queries
wp_cache_get('mp_docs_categories');
wp_cache_set('mp_docs_categories', $categories);

Database Optimization

• Use indexing on frequently queried columns
• Regularly clean up usage analytics
• Archive old versions

Frontend Optimization

• Enable Gzip compression
• Minify CSS/JS in production
• Use CDN for static assets
• Enable browser caching

Security Considerations

API Key Protection

• Never commit API keys to version control
• Use environment variables
• Rotate keys regularly
• Use minimal permission API keys

Data Sanitization

• All user input is sanitized
• SQL queries use prepared statements
• HTML output is escaped
• CSRF tokens on all forms

User Permissions

• Uses WordPress permission system
• Respects user roles and capabilities
• Non-authenticated users can view docs
• Only admins can manage docs

Advanced Customization

Custom Styling

Create custom-mp-docs.css:

:root {
  --mp-primary: #1f2937;
  --mp-secondary: #10b981;
}

.mp-docs-title {
  font-size: 40px;
}

Then enqueue in functions.php:

wp_enqueue_style('custom-mp-docs', get_stylesheet_directory_uri() . '/custom-mp-docs.css');

Custom AI System Prompt

Add filter in functions.php:

add_filter('mp_docs_ai_context', function($context, $question, $doc_id) {
    // Customize the context passed to AI
    return $context . "\n\nAlways mention MagePeople plugins.";
}, 10, 3);

Custom Search Handler

add_filter('mp_docs_search_results', function($results, $query) {
    // Filter or modify search results
    return array_filter($results, function($result) {
        return $result->featured === 1;
    });
}, 10, 2);

Support & Contributing

Getting Help

1. Check documentation at https://mage-people.com/docs
2. Open issue on GitHub
3. Contact support team

Contributing

1. Fork repository
2. Create feature branch
3. Make changes
4. Submit pull request

Changelog

Version 1.0.0

• Initial release
• Core documentation system
• AI chat integration
• SEO optimization
• Search functionality
• Analytics tracking

License

GPL v3 or later. See LICENSE file for details.

Credits

Created by MagePeople Team Inspired by Clerk.io documentation design

---

For more information, visit https://mage-people.com