Website Development on Wagtail CMS

Website Development Using Wagtail CMS

Wagtail is a Django CMS with a rich Draftail editor, StreamField for flexible content, and built-in headless API. Used by major organizations: NASA, Google, Torchbox, Mozilla. Well-suited for complex editorial projects on a Python stack.

Why Wagtail Instead of Django Without CMS

Wagtail adds to Django:

• Admin UI with live preview, revision history, workflow approval
• StreamField — block editor like Matrix in Craft
• Routable Pages — custom URLs within page without separate view
• Images — built-in image processing with focal point
• Documents — file management
• Snippets — reusable objects not tied to pages
• Search — full-text search via Elasticsearch or PostgreSQL

Architecture

myproject/
├── myproject/
│   ├── settings/
│   │   ├── base.py
│   │   ├── dev.py
│   │   └── production.py
│   ├── urls.py
│   └── wsgi.py
├── home/              # starter app
├── blog/              # blog app
│   ├── models.py
│   ├── migrations/
│   └── templates/
│       └── blog/
├── core/              # shared components
│   ├── models.py      # AbstractPage, Snippet classes
│   └── blocks.py      # StreamField blocks
└── requirements/
    ├── base.txt
    └── production.txt

Installation and Setup

pip install wagtail
wagtail start myproject
cd myproject
python manage.py migrate
python manage.py createsuperuser

# settings/base.py — key settings
INSTALLED_APPS = [
    'home',
    'blog',
    'core',
    'search',
    'wagtail.contrib.routable_page',
    'wagtail.contrib.search_promotions',
    'wagtail.contrib.settings',
    'wagtail.embeds',
    'wagtail.sites',
    'wagtail.users',
    'wagtail.snippets',
    'wagtail.documents',
    'wagtail.images',
    'wagtail.search',
    'wagtail.admin',
    'wagtail',
    'modelcluster',
    'taggit',
    'django.contrib.admin',
    # ...
]

WAGTAIL_SITE_NAME = 'My Site'
WAGTAILIMAGES_IMAGE_MODEL = 'core.CustomImage'  # custom images model
WAGTAILADMIN_BASE_URL = 'https://mysite.com'
WAGTAIL_ENABLE_WHATS_NEW_BANNER = False

Basic Page Models

# blog/models.py
from django.db import models
from wagtail.models import Page, Orderable
from wagtail.fields import RichTextField, StreamField
from wagtail.admin.panels import FieldPanel, InlinePanel, MultiFieldPanel
from wagtail.search import index
from wagtail.images.blocks import ImageChooserBlock
from wagtailmetadata.models import MetadataPageMixin
from modelcluster.fields import ParentalKey, ParentalManyToManyField
from taggit.models import TaggedItemBase

class BlogIndexPage(Page):
    intro = RichTextField(blank=True)

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

    subpage_types = ['blog.BlogPost']

    def get_context(self, request):
        context = super().get_context(request)
        posts = BlogPost.objects.live().public().order_by('-first_published_at')

        # Tag filtering
        tag = request.GET.get('tag')
        if tag:
            posts = posts.filter(tags__slug=tag)

        # Pagination
        from django.core.paginator import Paginator
        paginator = Paginator(posts, 12)
        page = request.GET.get('page')
        context['posts'] = paginator.get_page(page)
        return context


class BlogPostTag(TaggedItemBase):
    content_object = ParentalKey(
        'BlogPost',
        related_name='tagged_items',
        on_delete=models.CASCADE,
    )


class BlogPost(MetadataPageMixin, Page):
    date = models.DateField('Post date')
    intro = models.CharField(max_length=250)
    body = StreamField([
        ('heading',       blocks.CharBlock(form_classname='title')),
        ('paragraph',     blocks.RichTextBlock()),
        ('image',         ImageChooserBlock()),
        ('quote',         blocks.BlockQuoteBlock()),
        ('embed',         EmbedBlock()),
        ('code',          CodeBlock()),
        ('call_to_action', CTABlock()),
    ], use_json_field=True)
    tags = ClusterTaggableManager(through=BlogPostTag, blank=True)
    categories = ParentalManyToManyField('blog.BlogCategory', blank=True)

    search_fields = Page.search_fields + [
        index.SearchField('intro'),
        index.SearchField('body'),
        index.FilterField('date'),
    ]

    content_panels = Page.content_panels + [
        MultiFieldPanel([
            FieldPanel('date'),
            FieldPanel('tags'),
            FieldPanel('categories', widget=forms.CheckboxSelectMultiple),
        ], heading='Blog information'),
        FieldPanel('intro'),
        FieldPanel('body'),
        InlinePanel('gallery_images', label='Gallery images'),
    ]

    parent_page_types = ['blog.BlogIndexPage']
    subpage_types = []

StreamField Blocks

# core/blocks.py
from wagtail import blocks
from wagtail.images.blocks import ImageChooserBlock
from wagtail.embeds.blocks import EmbedBlock

class CTABlock(blocks.StructBlock):
    heading = blocks.CharBlock()
    text    = blocks.RichTextBlock(required=False)
    button_label = blocks.CharBlock()
    button_url   = blocks.URLBlock()
    variant = blocks.ChoiceBlock(choices=[
        ('primary',   'Primary'),
        ('secondary', 'Secondary'),
        ('outline',   'Outline'),
    ])

    class Meta:
        template = 'blocks/cta.html'
        icon     = 'pick'
        label    = 'Call to Action'


class TwoColumnBlock(blocks.StructBlock):
    left_column  = blocks.StreamBlock([
        ('paragraph', blocks.RichTextBlock()),
        ('image',     ImageChooserBlock()),
    ])
    right_column = blocks.StreamBlock([
        ('paragraph', blocks.RichTextBlock()),
        ('image',     ImageChooserBlock()),
    ])

    class Meta:
        template = 'blocks/two_column.html'
        icon     = 'grip'


class CodeBlock(blocks.StructBlock):
    language = blocks.ChoiceBlock(choices=[
        ('python',     'Python'),
        ('javascript', 'JavaScript'),
        ('bash',       'Bash'),
        ('sql',        'SQL'),
    ])
    code = blocks.TextBlock()

    class Meta:
        template = 'blocks/code.html'
        icon     = 'code'

Templates

<!-- templates/blog/blog_post.html -->
{% extends "base.html" %}
{% load wagtailcore_tags wagtailimages_tags %}

{% block content %}
<article>
    <header>
        <h1>{{ page.title }}</h1>
        <time datetime="{{ page.date|date:'Y-m-d' }}">
            {{ page.date|date:"d F Y" }}
        </time>
    </header>

    {% if page.header_image %}
        {% image page.header_image fill-1200x630-c100 as img %}
        <figure>
            <img src="{{ img.url }}" width="{{ img.width }}" height="{{ img.height }}" alt="{{ page.header_image.alt }}">
        </figure>
    {% endif %}

    <div class="post-body">
        {% for block in page.body %}
            {% include_block block %}
        {% endfor %}
    </div>

    <!-- Related posts -->
    {% with siblings=page.get_siblings.live.public.order_by('-first_published_at')[:3] %}
        {% if siblings %}
            <aside class="related">
                <h3>Read also</h3>
                {% for post in siblings %}
                    {% include "blog/_post_card.html" with post=post %}
                {% endfor %}
            </aside>
        {% endif %}
    {% endwith %}
</article>
{% endblock %}

Snippets — Reusable Content

# core/models.py
from wagtail.snippets.models import register_snippet

@register_snippet
class Testimonial(models.Model):
    author_name = models.CharField(max_length=255)
    company     = models.CharField(max_length=255, blank=True)
    text        = models.TextField()
    avatar      = models.ForeignKey(
        'wagtailimages.Image',
        null=True, blank=True,
        on_delete=models.SET_NULL,
        related_name='+',
    )

    panels = [
        FieldPanel('author_name'),
        FieldPanel('company'),
        FieldPanel('text'),
        FieldPanel('avatar'),
    ]

    def __str__(self):
        return f"{self.author_name} ({self.company})"

Wagtail API (Headless)

# settings/base.py
INSTALLED_APPS += ['wagtail.api.v2']

# urls.py
from wagtail.api.v2.views import PagesAPIViewSet
from wagtail.api.v2.router import WagtailAPIRouter
from wagtail.images.api.v2.views import ImagesAPIViewSet
from wagtail.documents.api.v2.views import DocumentsAPIViewSet

api_router = WagtailAPIRouter('wagtailapi')
api_router.register_endpoint('pages',     PagesAPIViewSet)
api_router.register_endpoint('images',    ImagesAPIViewSet)
api_router.register_endpoint('documents', DocumentsAPIViewSet)

urlpatterns = [
    path('api/v2/', api_router.urls),
    # ...
]

Development Timeline