Plugin that provides a Gutenberg block and an [include-mastodon-feed] shortcode to easily integrate mastodon feeds into wordpress pages. Supports personal and tag feeds. Account and post images are lazy loaded if preserveImageAspectRatio is set to true (default: false). The plugin is written in PHP
PricingFree downloadThe WordPress.org download is free. Pro versions, add-ons or external services may cost extra.
CompatibilityRequires WordPress 6.0 and PHP 8.2.
SourceWordPress plugins · Oct 17, 2026
01 / Source details
About this tool.
Plugin that provides a Gutenberg block and an [include-mastodon-feed] shortcode to easily integrate mastodon feeds into wordpress pages. Supports personal and tag feeds.
Account and post images are lazy loaded if preserveImageAspectRatio is set to true (default: false).
The plugin is written in PHP and generates native JavaScript to fetch and render the mastodon feed. No special libraries needed.
Styling works out-of-the-box. For a nice custom column layout check out the awesome Columns Guide by @oldrup – using WordPress native Gutenberg blocks (pattern json file included) and some css magic.
02 / Source details
Getting started.
01Upload the “include-mastodon-feed” directory to the “/wp-content/plugins/” directory.
02Activate the plugin through the “Plugins” menu in WordPress.
03Insert the “Mastodon Feed” block in Gutenberg editor or the “[include-mastodon-feed]” shortcode into any page.
14onlyMedia Show only statuses containing media (Default: false)
15preserveImageAspectRatio Preserve image aspect ratio (Default: false)
16imageSize Load small sized preview images or full size high quality images (Default: preview, full)
17imageLink Link image to status or image (Default: status, image)
18tagged Show only statuses that are tagged with given tag name (Default: false) No leading #, case insensitive, e.g.: tagged=”tagname”
19excludeTags Exclude statuses that are tagged with any of the given tag names (Default: false) Comma separated list of tags, no leading #, case insensitive, e.g.: excludeTags=”tag1,tag2″
20linkTarget Target for all links e.g. new tab would be “_blank” (Default: _self)
21showPreviewCards Show preview cards (Default: true)
22hideStatusMeta Hide status meta information, automatically also hides date and time (Default: false)
23hideDateTime Hide date and time from status meta information (Default: false)
24darkmode Enable dark mode (Default: false)
25text-loading Loading text (Default: Loading Mastodon feed…)
26text-noStatuses Text if no statuses are available (Default: No statuses available)
27text-boosted Text indicating boosted statuses (Default: boosted 🚀)
28text-viewOnInstance View status on instance link text (Default: view on instance)
29text-showContent Text for content warning buttons (Default: Show content)
30text-permalinkPre Text before post permalink (date & time) (Default: on)
31text-permalinkPost Text after post permalink (date & time) (Default: )
32text-edited Text indicating edited posts (Default: (edited))
33date-locale Locale for date string, used in toLocaleString() (Default: en-US)
Additional customizations
You can define several plugin constants to set custom default options that will be applied site-wide (e.g. date options can only be set as php constant to mitigate an XSS vulnerability).
34Open your wp-config.php file
35Search for the line /* Add any custom values between this line and the "stop editing" line. */
36Define the options you want to override between the line from step #2 and /* That's all, stop editing! Happy publishing. */
See the included config-example.php file for a full list of supported settings.
Pretty column layout example
Check out the awesome Columns Guide by @oldrup using WordPress native Gutenberg blocks (pattern json file included) and some custom css magic:
37Official Columns Guide
38Detailed how-to instructions and visual examples
03 / Source details
Frequently asked questions.
How do I find my account ID?
Please feel free to use this handy lookup tool
To look your ID up manually there are several ways.
As an instance admin you can easily read your user ID in the admin backend.
As regular user you can try an API v2 search to find your ID.
API v2 notes: * Change example.org to your instance * Replace username with your handle.
Use the following URL to get your ID:
https://example.org/api/v2/search?q=username@example.org&resolve=false&limit=5 How does caching work?
Server-side caching is disabled by default. When disabled every page load will trigger a new API request to your Mastodon instance for every single feed. This is how the public feeds API is intended and usually not a problem.
If you have a high-traffic site and want to help out your Mastodon instance you can enable caching globally or per shortcode. When enabled the plugin will cache the feed for 5 minutes as a default.
The plugin automatically uses any enabled cache plugin or the WordPress internal transient cache (= WordPress database). Only the statuses JSON response is cached – any media is still served from the Mastodon instance directly.
Note: If you Mastodon instance needs API authentication server-side caching is automatically enabled for all feeds that use authentication. That way your auth token is not exposed to your website visitors.
API authentication
If your Mastodon server needs API authentication you can use the auth parameter.
NOTE Do NOT add your API auth token directly to the plugin short code
To avoid exposing the auth token to website visitors you have to take extra steps to set up authentication support
See the very end of config-example.php for an in-depth configuration example
Steps to set up API authentication:
01Log into your Mastodon instance and go to Settings > Development (https://yourinstance.example.org/settings/applications)
02Create a new Application (any name, only check one single scope read:statuses )
03Add the auth mapping configuration to your wp-config.php (See very bottom of the included config-example.php )
04Add your custom auth reference to your shortcode
Known Issues / Todo
extend Gutenberg block capabilities (support more settings, enable backend preview) integrate i18n into translate.wordpress.org instead of text constants