Basic theming of my Wagtail site

April 6, 2020

I have decided to do this Wagtail blog article around theming, not because I have a lot to say, but because one of the key things we wanted to know was - "Is the theming in Wagtail going to be significantly quicker than in other CMS' (such as Drupal)".

tldr: If you have a design and someone that can churn out good static css/html, then I feel it is significantly quicker than Drupal

The process I used on this first time

  1. Get your HTML/CSS (
  2. Create a directory for your theme (eg. halcyonic) and extract the theme code into there
    note this would likely go in the mysite app folder NOT the roots static directory. The root static directory is managed by the `collectstatic` command.
  3. Alter base.html within your templates directory so it loads in the new css and js files (probably before all other css is loaded up)
  4. If you haven't already setup your templates, the error pages will help guide you, and the 404.html template is a good example to copy/paste, you will also likely want to copy some base html from the themes files (eg. wrappers/header/footer)
  5. Run `python collectstatic` this will compile all the theming into the main static directory ready for the templating engine to use

Some things I will do next time

  • Read up more on static files, and the capabilities available to manipulate them (both in Wagtail and Django)

Some useful learnings

  • Template files use DTL (Django Templating Language)
    • It is apparently easy to change to something else (such as Jinja2)
    • BUT note that from the Twig wiki page - "Twig is a template engine for the PHP programming language. Its syntax originates from Jinja and Django templates" so the difference to PHP/Twig is actually not too great
  • Directory structure is given a very nice outline on the wagtail docs: Writing Templates page
  • Wagtail Tags are quite useful, more than just images. For example, they can allow us to get things like
    • Rendering images
    • Loading other static files
    • Render richtext/html as safe html
    • Links to parent pages
    • Render the url of a page based solely on the slug passed in
  • Content can be varied based on whether 'preview' or 'live'
  • Admin styling
    • Not too complex, and can make a nice difference for a client

Further reading


Some wins worth noting

  • Has a very unopinionated base, which kinda means:
    • not spending hours overwriting default html/css
    • Embedding 3rd party js is much more like the examples given on the tutorials
  • Really didn't take long to embed a theme that I was given (whether from an online source, or a design team)
  • Forces all elements/states to be considered when theming - I feel that this is a plus as it allows me, as a developer, to get back to thinking about more than just 'does it work', things such as: accessibility, usability, requirements, quick wins, future improvements
  • Completely decoupled - for if you want to try out some shiny frontend system (I will likely look more into this in a future blog post though)