Known Caveats/Issues
Remote Request Timeouts
With external connections, HTTP requests are sent back and forth - creating posts, transferring images, syncing post updates, etc. In certain situations, mostly commonly when distributing posts with a large number of images (or very large file sizes), using poorly configured or saturated servers / hosts, or using plugins that add significant weight to post creation, Distributor requests can fail. Although we do some error handling, there are certain cases in which post distribution can fail silently. If distribution requests are taking a long time to load and/or failing, consider adjusting the timeout; you can filter the timeout for pushing external posts using the dt_push_post_timeout filter. More advanced handling of large content requests, and improved error handling is on the road map for a future update.
Post Meta Associations
A distributed post includes all of the post meta from the original version. Sometimes arbitrary post meta references an ID for another piece of content on the original site. Distributor does not "bring along" the referenced content or update references for arbitrary post meta (it will take care of updating references in the case of core WordPress features, such as the featured image ID). This issue is very common when using field management plugins like Advanced Custom Fields (ACF). This can be addressed on a case-by-case basis by extending the plugin. Distributor provides the distributor_register_data helper function for stored ID handling. Additionally, for external connections, you can manually handle post meta associations using the dt_push_post hook. For internal connections, use the dt_push_post hook. Note that while named the same, these hooks accept different parameters.
Stored ID Handling
Distributor often deals with data stored as ID references. This is common in WordPress, where IDs are used in block attributes, shortcodes, or post meta by popular plugins like ACF, Elementor, and Gravity Forms. However, when content is distributed to another site, these stored IDs may not match, leading to data loss or unexpected content.
To address this, Distributor provides a helper function: distributor_register_data. This function allows developers to register data references, specify where the data is located, define how to extract the ID, and register callbacks to process the data on both the source and target sites. More information can be found here.
Deleting Distributed Posts
When a post that has been distributed is deleted, the distributed copies will become unlinked ("forked") from the original and thus become editable. Similarly, when a distributed post is unpublished, distributed copies will not be unpublished. More sophisticated "removal" workflow is on the road map for a future update.
Gutenberg Block Mismatch
When distributing a Gutenberg post to another site that supports Gutenberg, if a block in the post does not exist on the receiving site, the block will be converted to a "Classic" HTML block.
Parent Posts
Distributor does not "bring along" parent (or child posts). If your post (or custom post type) has a parent or a child, it will distribute it as if it's an orphan.
Custom Post Type Support
Internal Connections (multisite) support multiple post types. In order for distribution to work with External Connections that have custom post type content, that post type needs to be registered with the argument show_in_rest => true on the external site.
Unable to Push to New Custom Post Types
If new Custom Post Types are created after establishing an External Connection, you will only be able to Pull those from an External Connection. To ensure you are able to Push new Custom Post Types to an External Connection, you will need to update the External Connection by editing it and then clicking the Update connection button.
Backwards Compatibility
While we strive to be mindful of backwards compatibility much the same way WordPress itself is, we do not currently guarantee continued interoperability between different versions of Distributor. We assume the current userbase for this plugin has a high degree of control over any site that has been set up as an external connection and urge you to keep Distributor up to date.
Distributing Post content
By default, post content is rendered before being copied. This means that shortcodes are expanded before being distributed and remote posts will not have the shortcode, but rather the expanded HTML content.
Distributing Authors
By default, distributed posts reference the original site as the "author" with a link to it. This can be altered by extending Distributor with custom code to make it sync authors.
Distributing Post Date
By default, the "post date" on distributed posts is the date its published on the remote site, not the date published on the origin site. This can be overridden by extending Distributor with custom code to make it preserve the post date.
Distributing Canonical URL
By default, canonical URL of distributed post will point to original content, which corresponds to SEO best practices. This can be overridden by extending Distributor with custom code and removing Distributor's default front end canonical URL filtering (look for 'get_canonical_url' and 'wpseo_canonical').
Drafts as Preferred Status
By default, drafts are the preferred status and can't be changed at the source site.
Conflicts with Security plugins
Oftentimes the communication Distributor attempts to make across sites using the REST API will be flagged by various security plugins and surreptitiously blocked. If you run into an issue like this, please reach out to the support for your security plugin and ask about getting Distributor unblocked (here is an example for doing so with Wordfence).