Commentail: my comment system for Wagtail

Why I built a comment system

I've been working with Wagtail and building websites with it for years. The same thing kept happening from one project to the next: I needed comments, so I wrote my own system again. Sometimes I brought one over from an older site, but by then it was already out of date. I'd have to rework it, adapt it to the new project, or often just start from scratch.

I once tried an existing Wagtail comment library based on django-comments-xtd. It wasn't a good fit for me, so I went back to building my own solutions.

For a long time, I wanted to make a separate library that I could use across websites and develop independently of any one project. I finally got around to it. That's how Commentail, a comment system for Wagtail CMS, came about.

I released the first public version, 0.1.0, on 17 October 2026. The 0.1.1 update followed on 19 October. I'm glad I finally got it out into the world. Now I'd like to show you what I've built.

What is Commentail?

Commentail installs as a Django app and runs on your own server. Comments are stored in your site's database, and you can moderate them directly in Wagtail. Email is sent through your project too, without an external comment platform.

The widget picks up your site's fonts and colors. If you need to change something, you can adjust CSS variables or override the templates. The interface is available in English and Russian. JavaScript makes it more convenient to use, but readers can still post, reply and edit their comments without it.

What it can do

For readers

• Comments without registration. Guests enter an email address and verify it using a link sent by email.
• Existing site accounts. If your site already has registration and login, Commentail works with those users.
• Replies and editing. Readers can reply to comments and edit their own messages, subject to your site settings. Replies are displayed with one level of nesting.
• Email notifications. Authors receive emails about direct replies to their comments. Each email includes an unsubscribe link.

For editors and developers

In the Wagtail admin, you can choose from four moderation modes, add rules for words and phrases, and import or export those rules as CSV. Settings apply to the whole site, with overrides for individual pages when needed. Moderators decide which comments to publish, but they don't rewrite someone else's text.

You can add comments to Wagtail pages and ordinary Django models; for the latter, you need to register an adapter. You can also supply your own avatars, display-name rules and CAPTCHA. The email queue lives in the database, so you don't need to install Redis or Celery separately.

The first update: what's new in 0.1.1

The first release worked with Wagtail 7.4 LTS, starting at 7.4.3, and Django 5.2. In 0.1.1, I added support for Wagtail 8.0 and Django 6.0–6.1. Not every combination of these versions works together, so here's the compatibility table:

The library works with Python 3.12, 3.13 and 3.14. Tests pass with a file-based SQLite database and PostgreSQL 16. If you're using Wagtail 7.4, choose Django 5.2 or 6.0: I don't support pairing it with Django 6.1.

I also fixed a few things:

• Email links. They now use the correct URLs even when Commentail is mounted under a nested path.
• Guest-name length. New names are limited to 40 characters. The count handles Unicode: a letter with a combining mark, for example, counts as one character. Leading and trailing spaces are removed. If a name is too long, the form shows an error; the server checks it before saving too. Existing names and names from user accounts are left as they are.
• The name-field translation. The guest-name label no longer picks up an unrelated translation of the word Name from another part of the site.

I've put the full list of changes and upgrade steps in the 0.1.1 release notes. This release adds no Commentail migrations. If you update Django or Wagtail at the same time, they may have migrations of their own.

Try it out

You can install version 0.1.1 from PyPI:

python -m pip install commentail==0.1.1

Next, add the app to your Django settings, connect the middleware and URL routes, and apply the migrations. In your template, add comments like this:

{% load commentail_tags %}
{% commentail_css %}
{% commentail_js %}
{% commentail page %}

Add the CSS and JavaScript tags once in your base template. Put the widget wherever you want the comments to appear. For guest email verification and reply notifications, configure email delivery and run the worker once a minute:

python manage.py process_commentail

The installation guide walks through all the steps. If you already have 0.1.0 installed, read the upgrade instructions and try the update on a test copy of your site first.

What's next

For now, comments are plain text only. There are no file uploads, likes, separate REST API or automatic updates that show new comments without reloading the page. There's also a caveat with email: if the SMTP server accepts a message but doesn't confirm it, a retry can deliver the same message again.

I'm happy with how Commentail has turned out, and I'm glad I can finally share it. If you build sites with Wagtail and need comments, give it a try. I'd like to hear how it works in other projects: what's convenient, what's missing and what took some extra effort to set up.

The code is on GitHub under the MIT license, the package is on PyPI, and the setup and configuration guides are in the Wiki. If you find a bug, open an issue and tell me what happened and how to make it happen again. Ideas and suggestions are welcome too.