Plugin that provides both a Gutenberg Block and [mastodon-feed] shortcode to easily integrate Mastodon feeds into WordPress pages. Supports personal and tag feeds with customizable styling options.
- Display personal Mastodon feeds by account ID
- Display tag-based feeds from any Mastodon instance
- Gutenberg Block editor support with visual preview and built-in account lookup
- Customizable styling with flexible color options
- Alpha transparency support for backgrounds and text colors
- Separate background and text color controls for optimal readability
- Filter options: exclude boosts, exclude replies, show only pinned, show only media
- Caching system to reduce API calls (configurable interval)
- Tabbed admin interface for easy configuration
- Fully translatable
- Privacy-friendly: No tracking, no external resources except Mastodon API calls
Place the following shortcode into your WordPress page as a shortcode block or just copy and paste right within a text block:
[mastodon-feed instance="YOUR-INSTANCE" account="YOUR-ACCOUNT-ID"]
For tag feeds:
[mastodon-feed instance="mastodon.social" tag="photography"]
The plugin includes a Gutenberg Block that provides a visual interface for embedding Mastodon feeds:
- Add the block: In the WordPress block editor, click the (+) button and search for "Mastodon Feed"
- Account Lookup: Use the built-in lookup tool to find your account ID:
- Enter your full Mastodon handle (e.g.,
[email protected]) - Click "Lookup Account ID"
- The block will automatically configure your instance and account ID
- Enter your full Mastodon handle (e.g.,
- Configure settings: Use the settings panels in the right sidebar:
- Account Lookup: Convert Mastodon handles to account IDs
- Feed Settings: Configure instance, account/tag, and post limit
- Filter Options: Set display filters (pinned, media, exclude boosts/replies)
- Display Options: Toggle preview cards, author info, and date/time display
Note: Date and time formatting for blocks is inherited from the admin settings page (Settings > Mastodon Feed > Display Options). This ensures consistent formatting across all feeds on your site.
| Attribute | Default value | Example | Description |
|---|---|---|---|
| instance | mastodon.social | instance="mastodon.social" | (required) Domain name of the instance without https:// |
| account | — | account="012345678910" | (required) Your account ID (a long number) |
| tag | — | tag="travel" | Use tag instead of account if you want to embed a tag feed instead of a personal feed |
| limit | 10 | limit="10" | Maximum number of posts to display |
| excludeBoosts | false | excludeBoosts="true" | Exclude boosted posts |
| excludeReplies | false | excludeReplies="true" | Exclude replies to other accounts |
| onlyPinned | false | onlyPinned="true" | Show only pinned posts |
| onlyMedia | false | onlyMedia="true" | Show only posts containing media |
| tagged | — | tagged="tagname" | Show only posts that are tagged with given tag name (without # symbol) |
| linkTarget | _blank | linkTarget="_self" | Target for all links (_blank, _self, _parent, _top) |
| showPreviewCards | true | showPreviewCards="false" | Show preview cards from posts |
| showPostAuthor | true | showPostAuthor="false" | Show post author information |
| showDateTime | true | showDateTime="false" | Show date and time in status meta information |
| dateTimeFormat | "Y-m-d h:i a" | dateTimeFormat="F j, Y" | PHP date format (see documentation) |
| text-noPosts | "No posts available" | text-noPosts="Empty!" | Text displayed when no posts are available |
| text-boosted | "boosted 🚀" | text-boosted="🚀" | Boosted post indicator text |
| text-showContent | "Show content" | text-showContent="View" | Text for content warning buttons |
| text-preDateTime | "on" | text-preDateTime="posted on" | Text before post permalink (date & time) |
| text-postDateTime | "" (empty) | text-postDateTime="UTC" | Text after post permalink (date & time) |
| text-edited | "(edited)" | text-edited="✏️" | Text indicating edited posts |
You can define several plugin constants to set custom default options that will be applied site-wide.
- 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 includes a comprehensive settings page accessible via Settings > Mastodon Feed in your WordPress admin. The settings are organized into tabs:
- Default Mastodon instance hostname
- Default number of posts to display
- Feed cache timeout (seconds)
- HTTP request timeout (seconds)
- Only show pinned posts
- Only show posts containing media
- Only show posts tagged with specific tag
- Exclude boosts
- Exclude replies
- Link target for post links (_blank, _self, _parent, _top)
- Show preview cards from posts
- Show post author
- Show date and time
- PHP date/time format
- Post background color (with alpha transparency support)
- Post font color (with alpha transparency support)
- Accent color (for links and highlights)
- Accent font color
- Border radius
- Customize all text strings used in the feed display
- Built-in tool to lookup account IDs from Mastodon handles
- Validates instance connectivity and account existence
- Clear feed cache button to force immediate refresh
The plugin is available through the official WordPress plugin directory https://wordpress.org/plugins/mastodon-feed/
- Log into your WordPress installation
- Go to "Plugins" and select "Add New"
- Search for "Mastodon Feed"
- Hit the "Install" button
- After installation hit the "Activate" button
- Go to Settings > Mastodon Feed to configure default options
- Click on the
<>Codein the top right of this page - Select
Download ZIP - Create a
mastodon-feedfolder in your WordPress plugins directory - Unpack all the files from the ZIP there
- Enable plugin in WordPress admin
- Configure settings and use the block editor or 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/mattsimpson/mastodon-feed.git- Enable plugin in WordPress admin
- Configure settings and use the block editor or shortcode
Note: The compiled block files are included in the repository, so no build step is required.
If you want to modify the block editor component:
- Make changes to files in
/src/block/ - Run
npm install(first time only) - Run
npm run buildto compile and test your changes locally - When ready to commit changes, commit only changes to the
src/directory. Not thebuild/directory. - Create a pull request to mastodon-feed main branch
Important: Developers should not commit their own build files. This will be done by the project maintainer at release.
The plugin includes a built-in account lookup tool! You can find it in:
- Block Editor: When adding a Mastodon Feed block, use the Account Lookup panel in the sidebar. Simply enter your full Mastodon handle (e.g.,
[email protected]) and click "Lookup Account ID" - Admin Settings: Go to Settings > Mastodon Feed > Account Lookup tab
The built-in tool will automatically find your account ID and configure the instance for you.
Alternative methods:
You can also use this handy external lookup tool from WolfGang.
Or, as a logged-in user, you can use an API v2 search to find 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 web browser (you must be logged in)
Yes! The plugin includes a comprehensive settings page under Settings > Mastodon Feed where you can customize:
- Post background and text colors
- Accent colors for links and highlights
- All text strings displayed in the feed
- Display options (show/hide various elements)
You can also override default values by defining constants in your wp-config.php file. See config-example.php for all available options.
The plugin is released under the Expat License (MIT) which is very permissive. Knock yourself out!
This plugin was inspired by and builds upon the work of others in the WordPress and Mastodon communities:
- WolfGang - For the original Include Mastodon Feed WordPress Plugin which served as inspiration and provided valuable insights for this implementation
- Automattic - For the WordPress ActivityPub Plugin which provided inspiration for integrating federated social networks with WordPress
Thank you to these projects and their contributors for helping make the WordPress ecosystem more connected to the Fediverse!