diff --git a/README.md b/README.md
new file mode 100644
index 0000000..46b8aa5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# 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
+
+### 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.