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
<?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`:

```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:

```html
{{ 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:

```yaml
---
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.