README

A comprehensive WordPress plugin that allows you to customize the domain used in permalinks without affecting your WordPress admin area, login functionality, or admin-ajax.php URLs. Perfect for CDN integration, domain migration, headless architectures that maintain the same path on the frontend application, or multi-domain/multi-site setups using reverse proxies.

Created and maintained with the Claude Sonnet 4 LLM.

Features

Core Functionality

• Custom Domain for Permalinks: Change the domain used in all public-facing URLs
• Protocol-Relative URLs: Convert URLs to protocol-relative format (//example.com/path) for better HTTPS/HTTP compatibility
• Admin Area Protection: WordPress admin (/wp-admin/) continues to use the original domain
• Login Page Protection: wp-login.php and registration URLs remain on the original domain
• AJAX Protection: admin-ajax.php URLs are preserved to maintain functionality
• WP GraphQL Compatible: Enhanced filtering prevents CORS issues with GraphQL and REST API requests from admin

Comprehensive URL Coverage

This plugin filters URLs at multiple WordPress hook points to ensure comprehensive coverage:

Content URLs

• Posts & Pages: Individual post and page permalinks
• Archive Pages: Category, tag, and custom taxonomy archives
• Author Pages: Author archive URLs
• Date Archives: Year, month, and day archive pages
• Search Results: Search result page URLs
• Pagination: Next/previous page navigation links

Feed URLs

• RSS Feeds: Main RSS2, RDF, and Atom feeds
• Comment Feeds: Site-wide and post-specific comment feeds
• Custom Feeds: Any custom feed URLs generated by WordPress

API & Technical URLs

• REST API: All WordPress REST API endpoints
• XML Sitemaps: WordPress core sitemap URLs
• Canonical URLs: Link rel="canonical" tags in HTML headers
• Shortlinks: WordPress shortlink URLs

Meta Tags & SEO

• Open Graph: og:url tags for social media sharing
• Twitter Cards: Twitter card URL meta tags
• SEO Plugin Support: Integration with popular SEO plugins:
  • Yoast SEO (canonical, Open Graph, Twitter Cards)
  • The SEO Framework (canonical URLs)
  • RankMath (canonical URLs)

Search Engine Integration

• Algolia Search: Automatic integration with Algolia Search plugin
  • Fixes permalinks during content indexing
  • Ensures search results show correct custom domain URLs
  • Maintains compatibility with search indexing operations
• XML Sitemaps: WordPress core sitemap URLs with custom domains

Content Filtering

• Post Content: URLs within post and page content
• Widget Content: URLs in text widgets and other widget content
• Navigation Menus: URLs in WordPress navigation menus

Multisite Support

• Network Administration: Centralized management across all sites in a network
• Site-Level Overrides: Individual sites can override network settings
• Bulk Operations: Apply settings to multiple sites at once
• Site Statistics: Monitor which sites have custom domains configured

Admin Interface

• Intuitive Settings Page: Easy-to-use admin interface with responsive design
• URL Type Selection: Choose which types of URLs to modify
• Real-time Testing: Test URL transformations before applying
• Visual Feedback: See before/after URL comparisons
• Validation: Input validation and error handling
• Consistent Layout: Properly aligned buttons and form elements across all screen sizes

Security & Performance

• Input Sanitization: All user inputs are properly sanitized
• Output Escaping: All outputs are escaped to prevent XSS
• Capability Checks: Proper permission verification
• Nonce Protection: CSRF protection for all forms
• Caching Support: Efficient caching to minimize performance impact

Cache Management

• Automatic Cache Purging: Automatically clears all major caching plugin caches when settings are changed
• Multi-Plugin Support: Compatible with popular WordPress caching plugins:
  • WP Rocket
  • W3 Total Cache
  • WP Super Cache
  • LiteSpeed Cache
  • WP Fastest Cache
  • Autoptimize
  • WP Optimize
  • Comet Cache
  • Cache Enabler
  • Hummingbird
  • SG Optimizer
• Object Cache Clearing: Purges WordPress object cache and plugin-specific caches
• Test URL Accuracy: The "Test URL Changes" button now shows accurate results by purging caches first
• Immediate Application: Settings changes are immediately visible without manual cache clearing

Protocol-Relative URLs

• Automatic Conversion: Convert absolute URLs to protocol-relative format (//example.com/path)
• Network-Level Control: Manage relative URLs across all sites in multisite networks
• HTTPS/HTTP Compatibility: Seamless switching between protocols
• CDN Optimization: Improve CDN performance and cross-domain compatibility
• Site-Level Override: Individual sites can control their relative URL preferences
• Smart Detection: Preserves admin URLs while converting frontend URLs

Data Preservation

• Optional Data Retention: Choose whether to keep plugin settings when uninstalling
• Update-Friendly: Preserve settings during plugin updates or temporary deactivation
• Network-Level Control: Network administrators can control data preservation across all sites
• Granular Control: Individual sites can override network preservation settings
• Smart Cleanup: When preservation is disabled, completely removes all plugin data
• Migration Support: Easily move plugin settings between environments

Installation

Preferred Method: GitHub Release

1. Download the latest release from GitHub Releases
2. Upload the downloaded ZIP file to your WordPress /wp-content/plugins/ directory
3. Extract the ZIP file
4. Activate the plugin through the 'Plugins' menu in WordPress

Alternative: Composer

If you manage your WordPress plugins with Composer, you can install this plugin:

composer require gokepelemo/custom-permalink-domain

Then activate the plugin through the WordPress admin.

Manual Installation

1. Download or clone the repository
2. Upload the entire custom-permalink-domain directory to your WordPress /wp-content/plugins/ directory
3. Activate the plugin through the 'Plugins' menu in WordPress

Configuration

1. Navigate to Settings → Permalink Domain in your WordPress admin
2. Enter your new domain (e.g., https://cdn.example.com)
3. Select which content types should use the custom domain
4. Click Save Settings

Use Cases

• CDN Integration: Serve content from a CDN domain
• Domain Migration: Test new domain without changing WordPress config
• Performance: Separate content delivery from admin functionality
• SEO: Maintain admin access while changing public URLs
• Protocol Flexibility: Use relative URLs for HTTPS/HTTP compatibility
• Cross-Domain Content: Improve compatibility with reverse proxies and load balancers

How It Works

The plugin uses WordPress filters to modify permalink generation:

• post_link - Blog post URLs
• page_link - Page URLs
• category_link - Category archive URLs
• tag_link - Tag archive URLs
• author_link - Author archive URLs
• attachment_link - Media attachment URLs

Third-Party Plugin Integration

The plugin includes specialized integrations for popular WordPress plugins:

Algolia Search Plugin

• algolia_post_shared_attributes - Fixes post permalinks during indexing
• algolia_searchable_post_shared_attributes - Fixes searchable post permalinks
• algolia_term_record - Fixes term/category permalinks during indexing

This ensures that when Algolia indexes your content, search results will show the correct custom domain URLs instead of the original domain.

SEO Plugins

• Yoast SEO: Canonical URLs, Open Graph URLs, Twitter Card URLs
• The SEO Framework: Canonical URL generation
• RankMath: Frontend canonical URLs

WP GraphQL Compatibility

The plugin includes special handling to prevent CORS issues with WP GraphQL by avoiding URL rewriting in admin contexts while maintaining functionality for public-facing requests.

Admin Features

• Current Status Display: Shows current WordPress URL vs custom domain
• URL Examples: Preview how URLs will change
• Validation: Prevents invalid URLs from being saved
• Help Text: Clear instructions and explanations

Security

• Capability checks (manage_options)
• Input sanitization with esc_url_raw()
• Settings validation
• Nonce protection through WordPress Settings API

Compatibility

• WordPress 5.0+
• PHP 7.4+
• Works with any permalink structure
• Compatible with most themes and plugins

Changelog

See CHANGELOG.md for the complete version history.

Support

For issues or questions, please check the plugin settings page for troubleshooting information.