Commentail

Self-hosted comments for Wagtail CMS

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

Current release: 1.0.0 · PyPI

English · Русский

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.

1.0.0 starts the stable API and compatibility policy with the feature set of 0.2.0 Beta, including recent comments, six languages and HTML emails. Version-to-version changelog · Roadmap. Changes and upgrade notes.

Why Commentail?

For readers	For editors	For developers
Guest email verification or existing site accounts	Four moderation policies	One template tag for Pages and registered objects
Inline replies and author editing	Site defaults and Page overrides	CSS properties and template overrides
Direct-reply email with unsubscribe	Word/phrase rules and CSV import/export	Replaceable avatars, names and CAPTCHA
Responsive layout and plain HTML fallbacks	Site-scoped group permissions	Database outbox; no Redis/Celery requirement

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 →

From 1.0.0, documented integration contracts follow the stable API and compatibility policy.

Compatibility

Component	Version / requirement
Python	3.12–3.14
Wagtail / Django	7.4.3+ in 7.4 / Django 5.2 or 6.0; 8.0.x / Django 5.2, 6.0 or 6.1
Database	File SQLite or PostgreSQL 16
UI and email languages	English, Russian, German, French, Spanish and Brazilian Portuguese
Frontend	Django templates, optional progressive JavaScript
License	MIT

This table describes the 1.0.0 release. CI defines all five framework pairs 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.

Languages

Alongside English and Russian, 0.2.0 includes German (de), French (fr), Spanish (es) and Brazilian Portuguese (pt-br) for the public UI, moderation/settings and all notification emails. The host site selects the active Django language; queued emails retain the recipient's saved language. User comments and rejection reasons are not translated. Documentation remains in English and Russian. Language configuration →

Quick start

1. Install

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

python -m pip install commentail==1.0.0

For the optional PostgreSQL driver, use python -m pip install 'commentail[postgres]==1.0.0'. You can also extract the source distribution and run python -m pip install . in its root. When upgrading, review the upgrade notes, including the 0.2.0 index migration and email overrides when coming from 0.1.1. For older installations, also review the 0.1.1 notes. 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.

Recent comments elsewhere

Use the recent-comments tag on a home page, sidebar or another template:

{% load commentail_tags %}
{% commentail_recent limit=5 as recent_comments %}
{% for comment in recent_comments %}
  <a href="{{ comment.url }}">{{ comment.author_name }}: {{ comment.text|truncatechars:120 }}</a>
{% endfor %}

Use page=page for one Page and include_replies=False for roots only. The list respects the current visitor's access and Site, requires a request context and must not be shared-cached. It needs no widget CSS or JavaScript. Fields, filters and caching →

4. Enable email and cleanup

Version 0.2.0 includes minimal HTML emails with the site name, clear action links and equivalent plain text. Existing host email overrides take precedence.

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:

Area	Guides
Connect	Installation · Runnable example
Configure	Site, Page and Python settings · Moderation · CSV rules
Reader behavior	Guests · Replies and editing
Customize	CSS and themes · Templates and email · Python callbacks · Django model adapters
Operate	SMTP and worker · Deployment · Security and privacy
Diagnose	Troubleshooting / FAQ · Example and testing · Performance and load checks

Release scope and verification

1.0.0 release 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. Historical checks also covered Chrome 142 on macOS and Windows ARM64 and Firefox 140 ESR on Windows ARM64; Chrome x64 used Windows emulation. 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 1.0.0. 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.