
jekyll-webmentions-static
A Jekyll plugin that fetches your Webmention.io mentions at build time and renders them as static HTML, with no JavaScript.
jekyll-webmentions-static fetches your Webmention.io mentions at Jekyll build time and renders them as plain static HTML. There’s no JavaScript, no client-side API call, and nothing to run in the browser. The output is static, so it works on GitHub Pages or any static host.
Webmentions are how the IndieWeb handles responses. When someone likes, reposts, or replies to your content from a platform that supports webmentions (Mastodon, Micro.blog, and others through Bridgy), those responses can show up on your site as first-class content.
How It Works
- At build time, the plugin fetches every mention for your domain from the Webmention.io API
- It caches them in
_webmentions_cache.jsonso it doesn’t fetch the same ones twice - Each post gets its mentions in
page.webmentions - The
{% webmentions %}Liquid tag renders them as styled HTML
Requirements
- A Webmention.io account (free)
- A
<link rel="me">pointing to your GitHub profile in your site’s<head>for authentication - Your Webmention.io API token
Installation
Add to your Gemfile:
gem "jekyll-webmentions-static"
Add to plugins: in _config.yml:
plugins:
- jekyll-webmentions-static
Configuration
webmentions:
token: YOUR_TOKEN # or use WEBMENTION_TOKEN env var (preferred for CI)
cache: true # cache fetched mentions (default: true)
cache_ttl: 3600 # seconds before re-fetching (default: 3600)
Add _webmentions_cache.json to your .gitignore.
For GitHub Actions, set WEBMENTION_TOKEN as a repository secret instead of putting the token in _config.yml.
Keep mentions fresh with a scheduled rebuild. Webmentions only update when your site rebuilds. If you don’t publish often, add a schedule trigger to your Pages workflow so they stay current:
on:
push:
branches: [main]
schedule:
- cron: '0 */6 * * *' # rebuild every 6 hours
Change the interval to suit your site. Daily (0 0 * * *) is fine for most sites.
Template Usage
Add the tag to your post layout:
{% webmentions %}
Or use the raw data in page.webmentions to render them your own way:
{% assign likes = page.webmentions | where: "type", "like-of" %}
<p>{{ likes.size }} likes</p>
Output Structure
The {% webmentions %} tag renders:
- Reaction counts: likes (♥), reposts (⟳), and bookmarks in pill badges, with tooltip text on hover
- Replies: each reply as a card with the author’s avatar, their name linked to their profile, the date, and the reply text

Styling
The plugin outputs unstyled semantic HTML. Every element has a BEM class name, so it’s easy to target:
/* Outer section */
.webmentions { }
/* Reaction count pills */
.webmentions__counts { }
.webmentions__likes { }
.webmentions__reposts { }
.webmentions__bookmarks { }
/* Replies section */
.webmentions__replies { }
.webmentions__replies-heading { }
/* Individual reply card */
.webmention__reply { }
.webmention__author { }
.webmention__avatar { } /* circular avatar img */
.webmention__author-name { } /* linked name */
.webmention__date { }
.webmention__content { }
Source
Available on GitHub and RubyGems.
gem install jekyll-webmentions-static

