Commentail

Self-hosted comments for Wagtail CMS

Moderated discussions, verified guests and inline replies — styled by your site.

Get started · Documentation · Wiki · Support

Commentail is a Django comments library for Wagtail 7.4 LTS and 8.0. Add a Django template tag to an article, moderate discussions inside Wagtail, and keep content, accounts and email delivery in your own application.

The widget inherits your site's typography and colors. CSS custom properties, replaceable templates and Python callbacks let you adapt it without a frontend framework or an external comments platform.

0.1.1 Beta adds Wagtail 8.0 and Django 6.x support. Version-to-version changelog · Roadmap. Changes and upgrade notes.

Why Commentail?

Comments are plain text with an adjustable 5000-character default. Optional clickable HTTP(S) links use safe attributes. Replies can address any visible message while keeping one visual nesting level. Moderators approve, reject, hide, restore or erase text; they never rewrite another author's words.

Published comments include Schema.org Comment microdata and JSON-LD, using the visible text and author name. Choose either format or disable output in Python. Structured-data guide →

Compatibility

This table describes the 0.1.1 beta release. All five framework pairs are tested on Python 3.12, 3.13 and 3.14 with both databases (30 combinations). Package bounds are Wagtail>=7.4.3,<8.1 and Django>=5.2,<6.2; only the pairs listed above are supported. Wagtail 7.4 with Django 6.1 is outside this matrix. Wagtail 8.1 and later require separate verification before support is declared.

Guest comments require configured SMTP and the scheduled worker. Registered users can comment without an email address, but receive no mail. Your site provides login and registration. No required external CDN or CAPTCHA service.

Quick start

1. Install

In your site's virtual environment, install the release:

python -m pip install commentail==0.1.1

For the optional PostgreSQL driver, use python -m pip install 'commentail[postgres]==0.1.1'. You can also install a downloaded wheel directly, or extract the source distribution and run python -m pip install . in its root. When upgrading from 0.1.0, review the upgrade notes, including guest-name validation and overridden forms. The 0.1.0 package retains its original Wagtail 7.4 and Django 5.2 limits.

2. Connect Django and Wagtail

• Add commentail and wagtail.contrib.settings to your existing INSTALLED_APPS.
• With PostgreSQL, also include django.contrib.postgres (required by Django 6.x checks).
• Insert commentail.middleware.CapabilityHeadersMiddleware before CSRF middleware.
• Retain the host session/authentication/messages middleware and template request context processor.
• Include Commentail URLs before Wagtail's catch-all:

path("commentail/", include("commentail.urls")),

Run python manage.py migrate, python manage.py check and your normal static collection. See the complete installation guide for settings, URL imports, CSRF draft recovery and deployment details.

3. Add the widget

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

Put the resource tags once in the base template and the widget in the article. The template controls where Page comments are available; the corresponding Page editor receives a Comments tab. Configure site defaults, then inherit or override on individual Pages. Review all is the initial moderation policy.

4. Enable email and cleanup

Configure Django's SMTP settings and schedule this once per minute:

python manage.py process_commentail

It sends the database outbox and removes expired transient records. Guests confirm email before moderation. Public submissions with an email are automatically subscribed to direct-reply notifications when mail is enabled; each reply email includes per-comment unsubscribe. Email setup and behavior →

Make it yours

The widget has a transparent surface and inherits the container's font and text color, following your site's light/dark theme. Load overrides after its stylesheet:

.commentail {
  --commentail-color-accent: var(--brand-link, #245a86);
  --commentail-border-radius: .5rem;
  --commentail-max-width: 100%;
}

Use GET_AVATAR to return a profile image URL, or return None for generated initials. Register ordinary Django models through OBJECT_ADAPTERS. Technical settings use a single COMMENTAIL dictionary with default and hostname overrides.

Documentation by task

The Wiki and the versioned guides cover the same topics. Start with the task you need:

Release scope and verification

0.1.1 beta notes describe the changes and upgrade steps; 0.1.0 release notes preserve the initial release contract. The source distribution includes the runnable Wagtail example, tests and guides; the wheel includes the runtime, translations, templates and static assets.

The CI workflow defines 30 framework/Python/database combinations, JavaScript, lint, migration drift, translations and source/wheel installation. Browser checks covered installed Safari, Chrome, Yandex Browser and Firefox with and without JS, plus selected VoiceOver scenarios and a phone. Previous major browser versions remain unverified; this is not an exhaustive accessibility or device certification.

There is no separate REST API, rich-text editor, uploads, likes, reports or live updates in 0.1.1. SMTP retries can duplicate mail after an uncertain delivery result. Host-specific themes, access rules and email delivery need their own acceptance checks.

Support Commentail

If Commentail helps your project, you can support maintenance, documentation and compatibility work. Contributions are optional.

Support via CloudTips

For questions and reproducible bugs, check the FAQ then open a GitHub issue. Do not include credentials, private comments or protected email links.