Title: Include Mastodon Feed Author: Wolfgang Published: December 2, 2022 Last modified: March 6, 2026 --- Search plugins ![](https://ps.w.org/include-mastodon-feed/assets/icon.svg?rev=2828003) # Include Mastodon Feed By [Wolfgang](https://profiles.wordpress.org/wolfgang101/) [Download](https://downloads.wordpress.org/plugin/include-mastodon-feed.2.1.0.zip) [Live Preview](https://pcd.wordpress.org/plugins/include-mastodon-feed/?preview=1) * [Details](https://pcd.wordpress.org/plugins/include-mastodon-feed/#description) * [Reviews](https://pcd.wordpress.org/plugins/include-mastodon-feed/#reviews) * [Installation](https://pcd.wordpress.org/plugins/include-mastodon-feed/#installation) * [Development](https://pcd.wordpress.org/plugins/include-mastodon-feed/#developers) [Support](https://wordpress.org/support/plugin/include-mastodon-feed/) ## Description 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. ## Blocks This plugin provides 1 block. * Mastodon Feed Embed the latest public posts of a Mastodon user ## Installation 1. Upload the “include-mastodon-feed” directory to the “/wp-content/plugins/” directory. 2. Activate the plugin through the “Plugins” menu in WordPress. 3. Insert the “Mastodon Feed” block in Gutenberg editor or the “[include-mastodon- feed]” shortcode into any page. #### Shortcode example ``` [include-mastodon-feed instance="YOUR-INSTANCE" account="YOUR-ACCOUNT-ID"] ``` #### Shortcode attributes * **instance** (required) Domain name of the instance without https:// (e.g. example. org) * **account** (required) The account ID (a long number – see FAQ on how to get it) * **tag** Use **tag** instead of **account** if you want to embed a tag feed instead of a personal feed * **cache** If wordpress should cache Mastodon server API calls (Default: false) Note: automatically enabled for feeds where auth is used * **auth** Auth key that should be used if Mastodon server API needs authentication * **limit** Maximum number of statuses (Default: 20) * **excludeReplies** Exclude replies to other accounts (Default: false) * **excludeConversationStarters** Exclude statuses that start with a user mention( Default: false) * **excludeBoosts** Exclude boosted statuses (Default: false) * **onlyPinned** Show only pinned statuses (Default: false) * **onlyMedia** Show only statuses containing media (Default: false) * **preserveImageAspectRatio** Preserve image aspect ratio (Default: false) * **imageSize** Load small sized preview images or full size high quality images( Default: preview, full) * **imageLink** Link image to status or image (Default: status, image) * **tagged** Show only statuses that are tagged with given tag name (Default: false) No leading #, case insensitive, e.g.: tagged=”tagname” * **excludeTags** 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″ * **linkTarget** Target for all links e.g. new tab would be “_blank” (Default: _self) * **showPreviewCards** Show preview cards (Default: true) * **hideStatusMeta** Hide status meta information, automatically also hides date and time (Default: false) * **hideDateTime** Hide date and time from status meta information (Default: false) * **darkmode** Enable dark mode (Default: false) * **text-loading** Loading text (Default: Loading Mastodon feed…) * **text-noStatuses** Text if no statuses are available (Default: No statuses available) * **text-boosted** Text indicating boosted statuses (Default: boosted 🚀) * **text-viewOnInstance** View status on instance link text (Default: view on instance) * **text-showContent** Text for content warning buttons (Default: Show content) * **text-permalinkPre** Text before post permalink (date & time) (Default: on) * **text-permalinkPost** Text after post permalink (date & time) (Default: ) * **text-edited** Text indicating edited posts (Default: (edited)) * **date-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). 1. Open your `wp-config.php` file 2. Search for the line `/* Add any custom values between this line and the "stop editing" line. */` 3. Define 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. ## FAQ ### How do I find my account ID? Please feel free to use [this handy lookup tool](https://wolfgang.lol/code/include-mastodon-feed-wordpress-plugin/) 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](https://github.com/wolfgang101/include-mastodon-feed/blob/master/config-example.php#L158) > for an in-depth configuration example **Steps to set up API authentication:** 1. Log into your Mastodon instance and go to Settings > Development (https://yourinstance. example.org/settings/applications) 2. Create a new Application (any name, only check one single scope `read:statuses`) 3. Add the `auth` mapping configuration to your `wp-config.php` (See very bottom of the included `config-example.php`) 4. Add 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 ## Reviews ![](https://secure.gravatar.com/avatar/cb9358ffd8587c3498800d9c404ab24e3f8cf81596d7038125e10a65c76226de? s=60&d=retro&r=g) ### 󠀁[Flexible and performant; a *much* better experience than big tech feed embeds.](https://wordpress.org/support/topic/flexible-and-performant-a-much-better-experience-than-big-tech-feed-embeds/)󠁿 [Bjarne Oldrup](https://profiles.wordpress.org/oldrup/) December 22, 2025 1 reply For almost a year now, I’ve been using Include Mastodon Feed on my personal blog and a pro bono client-site. The plugin is very flexible and with the meaningful HTML structure and class names, so I can style the posts in almost any thinkable way — just as it should be. The developer is very responsive and continuously improving the plugin. During 2025 that includes: Major performance improvements, including server side caching and lazy-loading. Major accessibility improvements initiated at the Global Accessibility Awareness Day. Support for even more attachment file formats like video and audio. Include Mastodon Feed is, to me, the obvious replacement for Facebook or Instagram feed embeds. It just works and does not require a premium plugin subscription or ever-changing API updates. Along with the ActivityPub plugin, Include Mastodon Feeds allows for productive, easy and fun integration with the Fediverse. I highly recommend it and it easily deserves five stars. ⭐⭐⭐⭐⭐ ![](https://secure.gravatar.com/avatar/456dd6c7821ccdb4e32d21623c40114af82047d690732145eb82c1d0acd5139c? s=60&d=retro&r=g) ### 󠀁[excellent customization](https://wordpress.org/support/topic/excellent-customization/)󠁿 [pellelle](https://profiles.wordpress.org/pellelle/) April 17, 2025 1 reply add-on works well and has good customizations. i was a bit confused about how “account id” differs from “account name”. but i got it working, and it’s great that there’s options for image aspect ratios and everything. thank you, developer! ![](https://secure.gravatar.com/avatar/8989b5ca4ae3f55861646953beb6eb3ed7d7a4584709efe811be84a06fbbf9ae? s=60&d=retro&r=g) ### 󠀁[Simple plug in that does the job and can be customised with CSS](https://wordpress.org/support/topic/simple-plug-in-that-does-the-job-and-can-be-customised-with-css/)󠁿 [pkingtiger](https://profiles.wordpress.org/pkingtiger/) May 7, 2024 2 replies Does what you need it to do in a simple way and can be customised with simple CSS to match the look and feel of your site.I would love to see some config options on how things are displayed:* Show / hide date & time at the top of each toot.* More placement options for the avatar. ![](https://secure.gravatar.com/avatar/7f4959894b0f82521a669fa74ab45d9accd8895be20ece8ff6feeb47fe68b54b? s=60&d=retro&r=g) ### 󠀁[Great plugin – thank you!](https://wordpress.org/support/topic/great-plugin-thank-you-145/)󠁿 [kenfortune](https://profiles.wordpress.org/kenfortune/) April 17, 2024 1 reply Love this plugin! Very easy to adjust the shortcode to customise the feed contents( eg. to exclude replies or boosts, to only show posts with images or with a certain tag etc). And if you are happy adding custom CSS to your wordpress, also fairly simple to get things looking just the way you want them. So happy this plugin exists. ![](https://secure.gravatar.com/avatar/c3534706ea2be3ec27436c1f1ff6e8dc385ace68fa08b32ecfb0f4ed1489a597? s=60&d=retro&r=g) ### 󠀁[Thank you so much](https://wordpress.org/support/topic/thank-you-so-much-182/)󠁿 [angelynng](https://profiles.wordpress.org/angelynng/) December 22, 2023 Simple. Works. Phew! ![](https://secure.gravatar.com/avatar/c7229529f9a6b40a35655dfd271146c079a81154f3c24bd6d5444492e494a5d4? s=60&d=retro&r=g) ### 󠀁[simple](https://wordpress.org/support/topic/simple-561/)󠁿 [Daniel](https://profiles.wordpress.org/dhoffmann/) November 11, 2023 thanks a lot! Works charming … [ Read all 16 reviews ](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/) ## Contributors & Developers “Include Mastodon Feed” is open source software. The following people have contributed to this plugin. Contributors * [ Wolfgang ](https://profiles.wordpress.org/wolfgang101/) “Include Mastodon Feed” has been translated into 3 locales. Thank you to [the translators](https://translate.wordpress.org/projects/wp-plugins/include-mastodon-feed/contributors) for their contributions. [Translate “Include Mastodon Feed” into your language.](https://translate.wordpress.org/projects/wp-plugins/include-mastodon-feed) ### Interested in development? [Browse the code](https://plugins.trac.wordpress.org/browser/include-mastodon-feed/), check out the [SVN repository](https://plugins.svn.wordpress.org/include-mastodon-feed/), or subscribe to the [development log](https://plugins.trac.wordpress.org/log/include-mastodon-feed/) by [RSS](https://plugins.trac.wordpress.org/log/include-mastodon-feed/?limit=100&mode=stop_on_copy&format=rss). ## Changelog #### 2.1.0 * feat: Gutenberg block now includes an account ID lookup tool, supports tag timelines and the post tag filter #### 2.0.1 * fix: added missing permission_callback to register_rest_route to avoid PHP Notice( thank you @h4r1m4u) #### 2.0.0 * feat: introducing the “Mastodon Feed” Gutenberg block – backwards compatible… shortcode will always be supported too * feat: increased required PHP version to 8.2 since there are no security updates for any version 8.1 or less * fix: INCLUDE_MASTODON_FEED_CACHE_DURATION constant name #### 1.17.0 * feat: added server side caching (see included `config-example.php` for global CACHE and CACHE_DURATION settings1). `cache` can be set as short code param as well. * feat: added API authentication support #### 1.16.0 * fix: local instance video urls * feat: added audio media support * feat: added excludeTags shortcode attribute – Exclude statuses that are tagged, posts containing any one of the given tags (comma separated list) will be excluded. Note: can lead to empty status list as the filtering is handled client-side. Mastodon API does not support this parameter natively. (thank you @zambunny) #### 1.15.1 * fix: added line break #### 1.15.0 * feat: now supports video attachments #### 1.14.0 * accessibility: add HTML lang attribute for even better screen reader support ( thank you @oldrup@mastodon.green) #### 1.13.1 * fix: removed unnecessary, broken aria-label functionality #### 1.13 Special release for Global Accessibility Awareness Day in collaboration with @oldrup@mastodon. green Happy [Accesssibility Day](https://accessibility.day) * accessibility (fix): image alt attributes – initial implementation was faulty * accessibility: added alt text to image / gifv attachments * accessibility: added alt text to avatar images * accessibility: added alt text to preview card media * accessibility: added descriptive aria-labels * accessibility: increased default text / background color contrast * accessibility: switched from DIV to semantic OL / LI structure #### 1.12 * accessibility: added image alt attribute (thank you @oldrup@mastodon.green) #### 1.11 * now favoring preview_url (smaler size) instead of remote_url (full size) for image previews (thank you @oldrup@mastodon.green) #### 1.10 * added image lazy loading for account and post images – post image lazy loading only works with preserveImageAspectRatio set to true (thank you @oldrup@mastodon. green) #### 1.9.11 * fixed typo (thank you @hjek) * cleaned up code after 1.9.10 release #### 1.9.10 * fixed XSS vulnerability: removed support for date-options as shortcode attribute completely – to mitigate an XSS vulnerability where authenticated attackers with contributor permission could insert malicious JavaScript (still can be set as constant in PHP code) #### 1.9.9 * fixed esc_url context that previously broke the URL for the Mastodon API JS ajax request (thank you @beach@illo.social) #### 1.9.8 * fix broken date-locale and date-options parameters (thank you @crusy@chaos.social) * improved string excaping for text parameters and added url escaping * removed unnecessary output buffering * fix license SPDX Identifier #### 1.9.7 * fix option to either display smaller image media attachment previews (default) or large image versions (thank you @beach@illo.social) #### 1.9.6 * fixed XSS vulnerability where authenticated attackers with contributor permissions could insert malicious JavaScript #### 1.9.5 * added option to either display smaller image media attachment previews (default) or large image versions (thank you @beach@illo.social) * added option to point image media attachment links to either status (default) or image #### 1.9.4 * added option to hide status meta information and date/time (thank you @PaulKingtiger@dice. camp) * added tag support – you can now embed tag feeds (thank you @martin@openedtech. social) * added option to show embedded images in original aspect ratio (thank you @beach@illo. social) * fix: correctly inject repeating emojis in display names and status texts (thank you @kanigsson@discuss.systems) #### 1.9.3 * fix: improved excludeConversationStarters detection (did not work correctly) * fix: undid last refactor to load JS inline with markup instead footer to fix problem with JS that was added to footer even if shortcode was not visibly rendered #### 1.9.2 * fix: style for embedded videos / GIFs * refactor: play gifv on mouseover * refactor: load markup related javascript in footer instead of embedding it directly with the html markup #### 1.9.1 * refactor: show meaningful message if no statuses are available * fix: broken excludeConversationStarters logic #### 1.9.0 * added option to exclude conversation starters (posts that start with a user mention) #### 1.8.1 * fix: boolean param validation was wonky * fix: stop links from overflowing (thanks to https://github.com/moan0s for contributing) * refactoring: improved styling of embedded images #### 1.8.0 * added option to show/hide preview cards * refactoring: introducing plugin namespace * refactoring: improved debug console output #### 1.7.0 * bumped tested wordpress version to 6.2 * added option to customize permalink text (before and after date/time) * added option to customize text indicating edited posts #### 1.6.0 * image attachments are now clickable (link to original status) #### 1.5.0 * added option to show only statuses with specific tag * added option to set link target to make links open in new tab * added option to set maximum number of statuses #### 1.4.2 * fixed styling issue with emojis in account display name #### 1.4.1 * fixed styling issue with boosted account links #### 1.4.0 * removed “view on instance” link and made date info clickable instead * added custom date locale and format option * fixed emoji and inline link styling issues in content blocks * fixed an issue with gifv media attachments * refactored option sanitizing and filtering #### 1.3.1 * updated documentation that plugin constants for setting custom default options have to be defined in `wp-config.php`, as the previous config.php file gets removed with every automatic plugin update * removed `config.php` support #### 1.3.0 * added new feed options: excludeReplies, onlyPinned, onlyMedia #### 1.2.0 * fixed broken JavaScript if post included media attachments other than images * fixed custom “view on instance” option * added option for custom content warning button text * added option to exclude boosted statuses * added support for gifv media attachments #### 1.1.0 * added support for more custom text overrides (loading, boosted, view on instnace) * switched to showing static avatars, animated avatars only on hover #### 1.0.1 * escaped options when echoing them * secured local file inclusion * changed versioning to semantic versioning – now including patch number #### 1.0 * Initial release ## Meta * Version **2.1.0** * Last updated **4 weeks ago** * Active installations **800+** * WordPress version ** 6.0 or higher ** * Tested up to **6.9.4** * PHP version ** 8.2 or higher ** * Languages * [Dutch](https://nl.wordpress.org/plugins/include-mastodon-feed/), [English (US)](https://wordpress.org/plugins/include-mastodon-feed/), [German](https://de.wordpress.org/plugins/include-mastodon-feed/), and [Swedish](https://sv.wordpress.org/plugins/include-mastodon-feed/). * [Translate into your language](https://translate.wordpress.org/projects/wp-plugins/include-mastodon-feed) * Tags * [feed](https://pcd.wordpress.org/plugins/tags/feed/)[mastodon](https://pcd.wordpress.org/plugins/tags/mastodon/) [status](https://pcd.wordpress.org/plugins/tags/status/) * [Advanced View](https://pcd.wordpress.org/plugins/include-mastodon-feed/advanced/) ## Ratings 5 out of 5 stars. * [ 16 5-star reviews ](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/?filter=5) * [ 0 4-star reviews ](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/?filter=4) * [ 0 3-star reviews ](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/?filter=3) * [ 0 2-star reviews ](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/?filter=2) * [ 0 1-star reviews ](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/?filter=1) [Add my review](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/#new-post) [See all reviews](https://wordpress.org/support/plugin/include-mastodon-feed/reviews/) ## Contributors * [ Wolfgang ](https://profiles.wordpress.org/wolfgang101/) ## Support Got something to say? Need help? [View support forum](https://wordpress.org/support/plugin/include-mastodon-feed/) ## Donate Would you like to support the advancement of this plugin? [ Donate to this plugin ](https://www.buymeacoffee.com/w101)