Building a Wagtail starter template
Time-saving tips for creating a template for new projects
We have a great feature in Wagtail that lets you load up a code template when you start a new project. All you have to do is add a flag to the Wagtail start command like this:
wagtail start project_name --template=https://github.com/yourtemplate/archive/main.zip
With the --template flag, you can pull in any starter template for Wagtail that you want to use. This can help you save time in your projects by pre-populating your project with a lot of the settings and templates and other bits and pieces that you use for your project.
This came in handy recently when I was preparing for teaching a tutorial at PyCon US. My co-teacher Scott Cranfill and I wanted to make sure we weren't burning too much of our teaching time on Wagtail set up. We wanted to spend as much time teaching folks about Wagtail's accessibility features instead. So I decided to create a template for the students to import some of the set up code so that we wouldn't waste precious time on copying and pasting.
To make this template, I set up everything in the project that we wanted people to have ahead of time. Things like custom models, CSS code, the blog templates, and more. I figured once I had everything where I wanted it to be, I could just slap /archive/main.zip at the end of my repository URL and that would be all I needed to do. Right?
Wrong. Every time I tested my repository in the wagtail start command, I was getting errors related to the template tags. Turns out that there's a bit more going on than a straight copy and paste when you use the --template flag. Wagtail is parsing the template code as the project is built and will try to execute any template tags you include (like {% load wagtailcore_tags %}).
The solution to avoiding that problem is pretty simple, it turns out. All you need to do is wrap the code in each of your template files with {% verbatim %}{% endverbatim %}. Here's of how that looks for the Blog Index Page template in our tutorial:
{% verbatim %} {% extends "base.html" %} {% load wagtailcore_tags %} {% block body_class %}template-blogindexpage{% endblock %} {% block content %} <h1>{{ page.title }}</h1> <div class="intro">{{ page.intro|richtext }}</div> {% for post in page.get_children %} <h2><a href="{% pageurl post %}">{{ post.title }}</a></h2> {{ post.specific.intro }} {{ post.specific.body }} {% endfor %} {% endblock %} {% endverbatim %}
That's not the only approach you can use. One of my co-workers at Torchbox also created a template using {% templatetag openblock %} and {% templatetag closeblock %} to replace the opening and closing template tags, so {% verbatim %}{% endverbatim %} isn't the only approach you can use. I just feel like the {% verbatim %}{% endverbatim %} approach is an easier one to maintain.
One I had those tags in place in my template files, the starter project loaded up just fine through the wagtail start command. All of our students were able to use it during our tutorial and we wound up with extra time to focus on accessibility testing and other things that were probably more useful to them than copying and pasting set up code.
As you can see in my repository, the starter template for our accessibility tutorial was very basic. You can use this trick to create your own starter template then make it as simple or as complicated as you want. What you include in it is largely up to you. But things you might find especially useful to start a project with include:
- Starter files and templates for your favorite frontend
- Common page models and apps (like a blog or news section)
- Custom models (such as the user, image, and document models)
- Deployment settings
- Files for key integrations
- Package settings
- Settings for your favorite database
- GitHub actions
- Linting
- And whatever else makes you start a project on a happy note
If you build your own template, please come show it off in our Wagtail Slack community or share it with me on your favorite social media platform. You can find me on X-Twitter, Mastodon, and LinkedIn. I'd love to hear from you. 😊
