121 lines
3.3 KiB
Markdown
121 lines
3.3 KiB
Markdown
# 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.
|