wagtail-html-editor

Philosophy

Wagtail's RawHTMLBlock is a simple textarea. While this simplicity is intentional, it can be limiting when editors need to write complex HTML layouts directly in the admin interface.

wagtail-html-editor bridges this gap by providing a VS Code-like editing experience within Wagtail's admin. Syntax highlighting, auto-indentation, Emmet support, and fullscreen mode make HTML coding in the admin not just possible, but comfortable.

This library is designed as a standalone package that enhances Wagtail's HTML editing capabilities.

Key Features

• Syntax Highlighting - HTML, CSS, and JavaScript with proper colorization
• Auto-indentation - Smart indentation like VS Code
• Dark/Light Mode - Follows Wagtail admin theme or manual toggle
• HTML Autocomplete - Tag completion, attribute suggestions
• Emmet Support - Expand abbreviations (e.g., div.container>ul>li*3)
• Search & Replace - Find and replace text with keyboard shortcuts (Ctrl+F / Ctrl+H)
• Fullscreen Mode - Expand editor to use the full panel for comfortable coding
• Auto-closing Tags - Automatic closing tag insertion
• Lightweight - Built on CodeMirror 6 with minimal bundle size

Use Cases

• HTML Layouts - Write complex HTML directly in Wagtail admin
• Custom Widgets - Embed third-party widgets with proper syntax highlighting
• Email Templates - Create HTML email templates with visual feedback
• SVG Content - Edit inline SVG with syntax support
• Script Injection - Add custom scripts with proper code editing

Installation

pip install wagtail-html-editor

Add to your INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    # ...
    'wagtail_html_editor',
    # ...
]

That's it! You can now use EnhancedHTMLBlock in your StreamFields.

Quick Start

1. Use in Your Page Model

from wagtail.models import Page
from wagtail.fields import StreamField
from wagtail.admin.panels import FieldPanel
from wagtail_html_editor.blocks import EnhancedHTMLBlock

class ContentPage(Page):
    body = StreamField([
        ('html', EnhancedHTMLBlock()),
        # ... other blocks
    ], blank=True, use_json_field=True)

    content_panels = Page.content_panels + [
        FieldPanel('body'),
    ]

2. Edit HTML in Admin

1. Go to your page in Wagtail admin
2. Add an "HTML" block to the body
3. Start coding with syntax highlighting!
4. Click the fullscreen button for a larger editing area
5. Use Emmet abbreviations for rapid HTML creation

3. Render in Template

{% load wagtailcore_tags %}

{% for block in page.body %}
    {% include_block block %}
{% endfor %}

Migrating from RawHTMLBlock

Already using Wagtail's RawHTMLBlock? Migration is simple - just replace the import and block class:

# Before
from wagtail.blocks import RawHTMLBlock

body = StreamField([
    ('html', RawHTMLBlock()),
])

# After
from wagtail_html_editor.blocks import EnhancedHTMLBlock

body = StreamField([
    ('html', EnhancedHTMLBlock()),
])

No database migration needed! As long as the block name (e.g., 'html') stays the same, your existing content will work seamlessly with the enhanced editor.

Editor Features

Syntax Highlighting

The editor provides proper syntax highlighting for:

• HTML tags and attributes
• Inline CSS (<style> blocks)
• Inline JavaScript (<script> blocks)
• Template syntax (Django/Jinja2)

Emmet Support

Expand abbreviations with Tab:

Search & Replace

Use keyboard shortcuts to open the search panel:

When in fullscreen mode, pressing Escape closes the search panel without exiting fullscreen.

Fullscreen Mode

Click the fullscreen button at the top-right of the editor:

• Uses the full left panel (preserves preview area)
• Press ESC or click Exit button to return
• Smooth enter/exit animations

Theme Support

The editor automatically follows Wagtail's theme:

• Auto (default): Follows Wagtail admin dark/light mode
• Light: Always use light theme
• Dark: Always use dark theme

Configuration

All settings are optional. Configure via WAGTAIL_HTML_EDITOR in your Django settings:

# settings.py
WAGTAIL_HTML_EDITOR = {
    "emmet": True,           # Enable Emmet abbreviation expansion
    "indent_size": 2,        # Number of spaces per indent (2 or 4)
    "indent_with_tabs": False,  # Use tabs instead of spaces
    "theme": "auto",         # "auto", "light", or "dark"
}

Available Settings

Troubleshooting

Editor Not Loading

Issue: The editor shows a plain textarea instead of CodeMirror.

Solutions:

1. Check browser console for JavaScript errors
2. Ensure static files are collected: python manage.py collectstatic
3. Clear browser cache (Cmd+Shift+R or Ctrl+Shift+R)

Emmet Not Working

Issue: Tab doesn't expand Emmet abbreviations.

Solutions:

1. Ensure emmet is True in settings (default)
2. Check that the cursor is at the end of the abbreviation
3. Some abbreviations may conflict with autocomplete - press Tab twice

Theme Not Matching Wagtail

Issue: Editor theme doesn't follow Wagtail's dark/light mode.

Solutions:

1. Ensure theme is set to "auto" in settings (default)
2. Reload the page after changing Wagtail's theme
3. Check browser console for theme detection errors

Requirements

See our CI configuration for the complete compatibility matrix.

Documentation

• Contributing Guide

Project Links

• GitHub Repository
• Issue Tracker

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

BSD 3-Clause License. See LICENSE for details.

Inspiration

• CodeMirror 6 - The code editor powering this package
• Emmet - The essential toolkit for web-developers
• VS Code - The editing experience we aim to bring to Wagtail