hugo-mastodon-comments/README.md

Hugo Mastodon Comments

A Hugo theme component that displays Mastodon comments on your blog posts. When you share a blog post on Mastodon, replies to that toot are automatically fetched and displayed as comments on your site.

How It Works

1. You publish a blog post and share it on Mastodon
2. The script searches your Mastodon timeline for toots containing links to your blog
3. When a matching toot is found, it fetches all replies (descendants)
4. Comments are displayed on your blog with author info, avatars, and engagement stats
5. Results are cached to minimize API calls

Setup

1. Copy Files

Copy the static/comments/ directory to your Hugo site's static folder or use this as a theme component.

2. Configure Backend

Create static/comments/config.php from the sample:

<?php
$config = [
    'mastodon-instance' => 'https://mastodon.social',
    'user-id' => 123456,           // Your Mastodon user ID
    'search-url' => 'https?://yourdomain.com',
    'cache_toots' => 300,          // Cache toots list for 5 minutes
    'cache_comments' => 300,       // Cache comments per toot for 5 minutes
    'debug' => false
];

To find your Mastodon user ID, check your profile API: https://mastodon.social/api/v1/accounts/lookup?acct=username

3. Configure Hugo

Add to your config.toml:

[params.mastodoncomments]
  user = "@username@mastodon.social"
  regex = "yourdomain.com"
  contact = "https://mastodon.social/@username"

4. Add to Template

Include the partial in your blog post layout:

{{ partial "comments.html" . }}

Usage

Display Comments

Comments are loaded automatically via JavaScript when visitors view a blog post. The script:

• Extracts the current page's permalink
• Queries the PHP backend to find matching Mastodon toots
• Displays replies as comments with full formatting

Optional: Direct Toot URL (Recommended for Performance)

For better performance, you can specify the Mastodon toot URL directly in your post's front matter:

---
title: "My Post Title"
mastodon_toot_url: "https://mastodon.social/@username/113456789012345678"
---

Benefits:

• Skips the entire toot search phase
• Reduces API calls significantly
• Faster page loads
• Works across different Mastodon instances
• Ensures the correct toot is always used

When to use:

• For any post where you know the Mastodon toot URL
• Especially recommended for popular or archived posts
• When you've shared the post on a different Mastodon instance

If no mastodon_toot_url is provided, the system automatically falls back to searching for toots containing the post URL.

Force Cache Refresh

To manually clear and rebuild the cache:

https://yourdomain.com/comments/getcomments.php?force_refresh=1

Cache Configuration

Adjust cache times based on your needs:

• Lower values (60-300s): Faster updates, more API calls
• Higher values (1800-3600s): Reduced load, slower updates

For most blogs, 300-1800 seconds is appropriate.

Requirements

• PHP 7.0+ with file_get_contents enabled
• Write permissions for cache files in the comments directory
• Network access to your Mastodon instance API

License

• PHP backend: AGPL-3.0-or-later
• JavaScript: AGPL-3.0-or-later
• Configuration samples: CC0-1.0

Credits

Based on work by Björn Schießle.