Lesson 13 / 22 · Commentail 1.3.2
Override templates when CSS cannot express the change, such as moving the date or applying the host theme to confirmation pages. Start with the smallest template that owns the desired structure.
Find the installed source
Run inside the site's environment:
python -c "import commentail; from pathlib import Path; print(Path(commentail.__file__).parent / 'templates' / 'commentail')"
Open the printed folder. Copy the required file into the project's templates/commentail/ using the same relative path. The project directory must precede app loaders in TEMPLATES[...]["DIRS"]. Do not edit .venv files; reinstalls replace them.
comment.html renders cards, replies.html renders replies, block.html wraps the widget, form.html handles main/reply forms, and edit-form.html handles edits. CAPTCHA templates are separate. Copy only files that need a change.
Style an action document
Copy the installed base.html to templates/commentail/base.html, find its existing extra_head block and replace that block only:
{% block extra_head %}
{% load static %}
<link rel="stylesheet" href="{% static 'css/commentail-custom.css' %}">
{% endblock %}
Style .commentail-document in the same CSS. Preserve title, heading, content and return_label blocks, language, viewport and the strict-origin referrer policy. A no-referrer policy can break native CSRF forms. Confirmation and unsubscribe must remain explicit POST actions; opening a link must not perform them automatically.
Preserve the form contract
Keep server action URLs, {% csrf_token %}, hidden key, reply_to, challenge and form_age, named inputs text, name, email, answer, and the commentail_contact honeypot. Editing needs edit_comment and the can_edit check. Do not reconstruct protected URLs yourself.
Progressive enhancement relies on .commentail[data-discussion], commentail-<id> anchors, form classes, navigation hooks, reply state and the network-error region. Compare against the complete template contract, including labels, ARIA attributes, error announcements and keyboard behavior.
Do not apply safe to raw user text. A card's built-in body has already been prepared by the library; arbitrary strings have not. Preserve JSON-LD/microdata unless intentionally disabled.
Test posting, replying, cancellation, editing, network errors and draft recovery. With arithmetic CAPTCHA also test native forms without JavaScript; required external challenges need JS. Compare overrides with the new bundled templates on every upgrade so an old copied form does not mask fixes.
Related lessons
- 12. Customize Commentail with CSS
- 14. Customize email wording and appearance
- 20. Upgrade and restore Commentail
Choose a sign-in method or comment as a guest below.