Commentail

Self-hosted comments for Wagtail CMS

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

Current release: 1.2.0 · PyPI

English · Русский

Get started · Screenshots · 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.

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 →

Documented integrations follow the stable API and compatibility policy.

Screenshots

Captured from Commentail 1.1.0, installed from PyPI in an isolated Wagtail 8.0.1 / Django 6.1.2 demo. Names and conversations are sample data. The public page uses a custom host theme; the widget and admin screens are the released package, without template overrides.

On the site: a discussion about Wagtail, Django templates and progressive enhancement, with a threaded reply and a highlighted editor.

Inside Wagtail: the moderation queue, expanded site/page, status and date filters, and two comments selected for bulk actions.

Compatibility

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.

The Wagtail 8 CI stacks select 8.0.1 or a newer patch within 8.0.

Guest comments require configured Django email delivery and scheduled background processing. Use SMTP or another Django EMAIL_BACKEND, and schedule the command or commentail.background.process_pending() through your existing task queue. 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. See email setup.

Languages

English (en), Russian (ru), German (de), French (fr), Spanish (es) and Brazilian Portuguese (pt-br) are available 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. The guides are in English; this README is also available in Russian. Language configuration →

Quick start

1. Install

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

python -m pip install commentail==1.2.0

For the optional PostgreSQL driver, use python -m pip install 'commentail[postgres]==1.2.0'. For an existing installation, follow the upgrade guide for your target version.

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 email backend and run this command once per minute:

python manage.py process_commentail

The command sends queued mail and removes expired temporary records. Guests confirm their email before moderation. Authors with email are subscribed to direct-reply notifications when mail is enabled; every reply email includes per-comment unsubscribe.

You can configure an API-based Django backend and schedule commentail.background.process_pending() in your project's queue instead of a separate command job. Choose one schedule. Backend acceptance does not prove inbox delivery. Backend setup, scheduling and verification →

5. Check the integration

Submit a comment while signed in, approve it in Comments, then try a reply and an eligible edit. In a separate browser session, submit as a guest and complete email confirmation. Check the real site's theme, permissions and mail delivery. Deployment checks →

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 →

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. No custom properties are required for the default appearance. To customize it, 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:

Verification and limits

See the changelog and release/upgrade guides for version-specific changes. 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. Local checks and hosted CI are separate; inspect the workflow for the revision you use. Browser/accessibility coverage and its limits are documented in Example and testing.

There is no separate REST API, rich-text editor, uploads, likes, reports or live updates. Mail retries can duplicate delivery after an uncertain backend 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.