Skip to content
Jan’s Blog

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.)

  1. Installation
  2. Configuration
  3. Media
  4. Privacy
  5. Gutenberg
  6. For Developers
    1. Custom Formatting
    2. Prevent Featured Images from Being Posted
    3. Prevent Attached Images from Being Posted
    4. Disable All Images
    5. Share Programmatically Created Posts, and More
    6. Disable Default Sharing
    7. Miscellaneous API Arguments
      1. Visibility
      2. Threaded Toots
  7. Debugging
  8. Links

Installation

The plugin’s available from WordPress.org’s plugin repo, so you can just head into WP Admin > Plugins > Add New, search for share on mastodon, and install and activate from there.

Configuration

Tell the Share on Mastodon settings page—visit Settings > 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.)

Media

When a Featured Image is set, Share on Mastodon will try to include it. This behavior can be disabled using the share_on_mastodon_featured_image filter.

Share on Mastodon will also try to include attached images. (Images uploaded through the Edit Post screen. Note: These images don’t necessarily occur in the actual post in question.) This behavior, too, can be disabled, using the share_on_mastodon_attached_images filter.

No more than four images will ever be included. (A hard limit imposed by Mastodon.)

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.

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.

Tooting featured images can easily be disabled:

// Never upload featured images.
add_filter( 'share_on_mastodon_featured_image', '__return_false' );

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. Disable them all:

// Never upload featured images.
add_filter( 'share_on_mastodon_attached_images', '__return_false' );

Or on a per-post-type basis:

add_filter( 'share_on_mastodon_attached_images', function( $enabled, $post ) {
  if ( 'post' === $post->post_type ) {
    return false;
  }

  return $enabled;
}, 10, 2 );

Disable All Images

You guessed it:

// Fully disable images.
add_filter( 'share_on_mastodon_featured_image', '__return_false' );
add_filter( 'share_on_mastodon_attached_images', '__return_false' );

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.

To work around this, e.g., for posts created through a third-party app, there’s a share_on_mastodon_enabled filter:

// Always share supported Post Types.
add_filter( 'share_on_mastodon_enabled', '__return_true' );

You could use the same filter to prevent, e.g., certain taxonomies from being shared.

add_filter( 'share_on_mastodon_enabled', function( $is_enabled, $post_id ) {
  if ( has_category( 'my-category-slug', $post_id ) ) {
    return false;
  }

  return $is_enabled;
}, 10, 2 );

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.