Plugin that provides 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.
Place the following shortcode right into the page. Either as shortcode block or just copy and paste right within a text block:
[include-mastodon-feed instance="YOUR-INSTANCE" account="YOUR-ACCOUNT-ID"]
| Attribute | Default value | Example | Description |
|---|---|---|---|
| instance | instance="example.org" | (required attribute) Domain name of the instance without https:// | |
| account | id="012345678910" | (required attribute) Your account ID (a long number) | |
| tag | tag="travel" | usetag instead of account if you want to embed a tag feed instead of a personal feed | |
| cache | false | cache="true" | If wordpress should cache Mastodon server API calls |
| auth | auth="auth_reference" | DO NOT USE your API auth token. See API Authentication for details | |
| limit | 20 | limit="10" | Maximum number of statuses |
| excludeBoosts | false | excludeBoosts="true" | Exclude boosted statuses |
| excludeReplies | false | excludeReplies="true" | Exclude replies to other accounts |
| excludeConversationStarters | false | excludeConversationStarters="true" | Exclude statuses that start with a user mention |
| onlyPinned | false | onlyPinned="true" | Show only pinned statuses |
| onlyMedia | false | onlyMedia="true" | Show only statuses containing media |
| preserveImageAspectRatio | false | preserveImageAspectRatio="true" | Preserve image aspect ratio |
| imageSize | "preview" | imageSize="full" | Load small sized preview images or full size high quality images |
| imageLink | "status" | imageLink="image" | Link image to status or image |
| tagged | false | tagged="tagname" | Show only statuses that are tagged with given tag name (no #!) |
| excludeTags | false | excludeTags="tag1,tag2" | Exclude statuses that are tagged - posts containing any one of the given tags will be excluded (no #!) |
| linkTarget | "_self" | linkTarget="_blank" | Target for all links |
| showPreviewCards | true | showPreviewCards="false" | Show preview cards |
| hideStatusMeta | false | hideStatusMeta="true" | Hide status meta information (automatically also hides date and time) |
| hideDateTime | false | hideDateTime="true" | Hide date and time from status meta information |
| darkmode | false | darkmode="true" | Enable dark mode |
| text-loading | "Loading Mastodon feed..." | text-loading="Loading ⏳" | Loading text |
| text-noStatuses | "No statuses available" | text-noStatuses="💩" | Text if no statuses are available |
| text-boosted | "boosted 🚀" | text-boosted="🚀" | Boosted status indicator text |
| text-viewOnInstance | "view on instance" | text-viewOnInstance="🔗" | View status on instance link text |
| text-showContent | "Show content" | text-showContent="👀" | Text for content warning buttons |
| text-permalinkPre | "on" | text-showContent="📅" | Text before post permalink (date & time) |
| text-permalinkPost | "" | text-showContent="📅" | Text after post permalink (date & time) |
| text-edited | "(edited)" | text-showContent="✏" | Text indicating edited posts |
| date-locale | "en-US" | date-locale="de-DE" | Locale for date string, used in toLocaleString() |
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).
- Open your
wp-config.phpfile - Search for the line
/* Add any custom values between this line and the "stop editing" line. */ - Define the options you want to override between this line and
/* That's all, stop editing! Happy publishing. */
See config-example.php for a full list of supported settings.
The plugin is available through the official Wordpress plugin directory https://wordpress.org/plugins/include-mastodon-feed/
- Log into your Wordpress installation
- Go to "Plugins" and select "Add New"
- Search for "Include Mastodon Feed"
- Hit the "Install" button
- After installation hit the "Activate" button
- Click on the
<>Codein the top right of this page - Select
Download ZIP - Create a
include-mastodon-feedfolder in your Wordpress plugins directory - Unpack all the files from the ZIP there (files only, no sub-directory)
- Enable plugin in Wordpress
- Use shortcode
If you are familiar with Github you can clone the repository right into your Wordpress plugins folder
- SSH into your webserver
cd /path/to/wordpress/wp-content/pluginsgit clone https://github.com/wolfgang101/include-mastodon-feed.git- Enable plugin in Wordpress
- Use shortcode
- integrate i18n into translate.wordpress.org instead of text constants
- re-build plugin as custom gutenberg block
Please feel free to use this handy lookup tool
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
Use the following URL to get your ID:
https://example.org/api/v2/[email protected]&resolve=true&limit=5
- Change
example.orgto your instance - Replace
usernamewith your handle. - Open the URL in your webbrowser
Note: You must be logged in to do that
The plugin is released unter the Expat License which is very permissive. Knock youself out!
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.
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:
- Log into your Mastodon instance and go to Settings > Development (https://yourinstance.example.org/settings/applications)
- Create a new Application (any name, only check one single scope
read:statuses) - Add the
authmapping configuration to yourwp-config.php(See very bottom of config-example.php) - Add your custom
authreference to your shortcode