Share on Mastodon
Automatically share WordPress posts on Mastodon. You choose which Post Types are shared. (Sharing can still be disabled on a per-post basis.)
Quick note: This short guide uses the terms “sharing,” “cross-posting,” and “syndication” more or less interchangeably. (While by default the plugin only shares, or posts, a title and permalink, it can be configured to cross-post, e.g, entire short posts.)
Installation
The plugin’s available from WordPress.org’s plugin repo, so you can just visit your WordPress’ admin interface, Plugins > Add New, and search for share on mastodon, and then install and activate from there.
Configuration
The plugin’s settings can be found at Settings > Share on Mastodon.
Setup
Tell Share on Mastodon about your instance URL, and make sure to hit Save Changes. You’ll then be able authorize WordPress to post on your behalf.
Select the Post Types for which sharing to Mastodon should be possible, too. (Sharing can still be disabled on a per-post basis.)
Images
Mastodon supports up to 4 image attachments.
By default, the plugin uploads featured and attached—useful for, e.g., (re)creating short “image galleries”—images.
The Images tab’s settings let you change this behavior.
E.g., to disable image uploads and instead rely on Mastodon’s auto-generated “link preview cards,” simply disable all checkboxes on the Images tab.
Developers can exert even more fine-grained control using the share_on_mastodon_featured_image
and share_on_mastodon_attached_images
filters.
Advanced
Delayed Syndication
There have been remarks about images sometimes not going through for posts created through WordPress’s XML-RPC endpoint (i.e., mobile apps and the like).
This can be solved by slightly delaying—by one minute or so—syndication. Share on Mastodon comes with a setting to delay posting. Set it to anywhere between, e.g., 60
and 300
(seconds) to see if that resolves the issue.
Opt-In
In order to avoid “accidental” sharing, you can make sharing “opt-in.”
Share Always
You can also force sharing, which will attempt to share each and every post (that isn’t private or otherwise protected), regardless of the Share on Mastodon checkbox state.
This can come in handy when you mostly post using, e.g., a third-party app (and thus can’t set the checkbox in WordPress’ admin interface).
Micropub
This setting is hidden unless you also have the Micropub plugin installed.
Share on Mastodon can be added as a Micropub syndication target, allowing you to enable (or disable) cross-posting right from your Micropub client.
Privacy
By default, all toots sent via this plugin are public. For unlisted or followers-only toots, have a look at the share_on_mastodon_toot_args
filter.
Gutenberg
This plugin now uses WordPress’ Meta Box API—supported by Gutenberg—to store per-post sharing settings, which makes it 100% compatible with the new block editor.
For Developers
After successfully posting to your Mastodon instance, WordPress stores the resulting URL in a post meta (or custom) field named _share_on_mastodon_url
. Using get_post_meta( get_the_ID(), '_share_on_mastodon_url', true )
, it’s possible to retrieve this value and, e.g., display a front-end link to the relevant Mastodon status.
It’s also this custom field that, if set, will prevent a post from being shared more than once. Clicking “Unlink,” however, in the Share on Mastodon’s meta box, will clear its value, and allow crossposting once more—but will not actually remove any earlier toots.
Share on Mastodon also comes with a fair number of filters that allow tweaking its behavior.
Note: A great deal of these filter hooks (those relating to images, “opt-in,” and “share always”) have since been “converted” to “proper” settings. Please have a look at Share on Mastodon’s settings first.
Also know that whatever is set on the plugin’s settings page will always be overridden by any filter callbacks in PHP.
Custom Formatting
By default, shared statuses look something like:
My Awesome Post Title https://url.to/original-post/
Mastodon is smart enough to then try and find things like an Open Graph image and description for that URL. There’s no need for a link shortener, either.
If you’d rather format toots differently, however, there’s a share_on_mastodon_status
filter.
Example: If all posts you share are short, plain-text messages and you want them to appear exactly as written and without a backlink—and essentially create a WordPress front end to Mastodon—then the following couple lines of PHP would handle that.
add_filter( 'share_on_mastodon_status', function( $status, $post ) {
$status = wp_strip_all_tags( $post->post_content );
return $status;
}, 10, 2 );
Same example, but with a permalink at the end:
add_filter( 'share_on_mastodon_status', function( $status, $post ) {
$status = wp_strip_all_tags( $post->post_content );
$status .= "\n\n" . get_permalink( $post );
return $status;
}, 10, 2 );
We can even append WordPress tags as hashtags:
add_filter( 'share_on_mastodon_status', function( $status, $post ) {
$tags = get_the_tags( $post->ID );
if ( $tags ) {
$status .= "\n\n";
foreach ( $tags as $tag ) {
$status .= '#' . preg_replace( '/\s/', '', $tag->name ) . ' ';
}
$status = trim( $status );
}
return $status;
}, 11, 2 );
Note: Most Mastodon instances will simply reject posts that are over 500 characters long. This WordPress plugin does currently not check this upfront, or warn you.
Prevent Featured Images from Being Posted
If you wanted to disable featured images only for a certain post type, you could do so:
add_filter( 'share_on_mastodon_featured_image', function( $enabled, $post ) {
if ( 'post' === $post->post_type ) {
return false;
}
return $enabled;
}, 10, 2 );
Prevent Attached Images from Being Posted
The same is true for images attached to a post.
add_filter( 'share_on_mastodon_attached_images', function( $enabled, $post ) {
if ( 'post' === $post->post_type ) {
return false;
}
return $enabled;
}, 10, 2 );
Share Programmatically Created Posts, and More
Even supported (per their Post Type) posts won’t be shared if not posted through WP Admin, as the “Share on Mastodon” checkbox value will not have been saved.
The one exception is Micropub clients that support syndication targets. These “just work.”
In all other cases, you’re going to have to somehow “tell” WordPress to share these posts after all; that’s why the “Share Always” setting exists.
The older share_on_mastodon_enabled
filter is up for deprecation.
Disable Default Sharing
Somewhat related: Share on Mastodon’s checkbox is enabled by default. Adding this to, e.g., your theme’s functions.php
changes that:
add_filter( 'share_on_mastodon_optin', '__return_true' );
Miscellaneous API Arguments
This filter’s applied right before sending a POST request to your Mastodon instance. Use it to add or remove any of the parameters supported by Mastodon’s API.
Custom Visibility
Modify a toot’s visibility by added a visibility
argument:
add_filter( 'share_on_mastodon_toot_args', function( $args ) {
$args['visibility'] = 'private'; // Only followers will get to see this message.
return $args;
} );
Threaded Toots
One possible application is threaded toots.
add_filter( 'share_on_mastodon_toot_args', function( $args ) {
$status = $args['status'];
// Some code, like a regex, that determines a parent post, if any, based on
// what's in `$status`.
$post_parent = <some-WP_Post-object>;
// Convert an earlier Mastodon URL to a status ID.
$toot_id = basename( get_post_meta( $post_parent->ID, '_share_on_mastodon_url', true ) );
if ( ! empty( $toot_id ) ) {
// Add to existing thread.
$args['in_reply_to_id'] = $toot_id;
}
return $args;
} );
Debugging
If you’ve added define('WP_DEBUG', true);
to wp-config.php
, the plugin settings page will show some debugging info.
If debug logging is enabled as well, connection errors will be logged to WordPress’s debug log.
Links
- An earlier blog post on customizing “Share on Mastodon” statuses
- A blog post on crossposting entire threads to Mastodon
- A blog post on using Share on Mastodon’s filter hooks to also cross-post audio and video
- WordPress.org →
- GitHub →