wagtail/docs/reference/project_template.md

(project_templates_reference)=

The project template

By default, running the wagtail start command (e.g. wagtail start mysite) will create a new Django project with the following structure:

mysite/
    home/
        migrations/
            __init__.py
            0001_initial.py
            0002_create_homepage.py
        templates/
            home/
                home_page.html
        __init__.py
        models.py
    search/
        templates/
            search/
                search.html
        __init__.py
        views.py
    mysite/
        settings/
            __init__.py
            base.py
            dev.py
            production.py
        static/
            css/
                mysite.css
            js/
                mysite.js
        templates/
            404.html
            500.html
            base.html
        __init__.py
        urls.py
        wsgi.py
    Dockerfile
    manage.py
    requirements.txt

Using custom templates

To use a custom template instead, you can specify the --template option when running the wagtail start command. This option accepts a directory, file path, or URL of a custom project template (similar to {option}django-admin startproject --template <django:startproject --template>).

For example, with a custom template hosted as a GitHub repository, you can use a URL like the following:

wagtail start myproject --template=https://github.com/githubuser/wagtail-awesome-template/archive/main.zip

See Templates (start command) for a list of custom templates you can use for your projects.

Default project template

The following sections are references for the default project template:

The "home" app

Location: /mysite/home/

This app is here to help get you started quicker by providing a HomePage model with migrations to create one when you first set up your app.

Default templates and static files

Location: /mysite/mysite/templates/ and /mysite/mysite/static/

The templates directory contains base.html, 404.html and 500.html. These files are very commonly needed on Wagtail sites, so they have been added into the template.

The static directory contains an empty JavaScript and CSS file.

Django settings

Location: /mysite/mysite/settings/

The Django settings files are split up into base.py, dev.py, production.py and local.py.

• base.py This file is for global settings that will be used in both development and production. Aim to keep most of your configuration in this file.

• dev.py This file is for settings that will only be used by developers. For example: DEBUG = True

• production.py This file is for settings that will only run on a production server. For example: DEBUG = False

• local.py This file is used for settings local to a particular machine. This file should never be tracked by a version control system.

On production servers, we recommend that you only store secrets in ``local.py`` (such as API keys and passwords). This can save you headaches in the future if you are ever trying to debug why a server is behaving badly. If you are using multiple servers which need different settings then we recommend that you create a different ``production.py`` file for each one.

Dockerfile

Location: /mysite/Dockerfile

Contains configuration for building and deploying the site as a Docker container. To build and use the Docker image for your project, run:

docker build -t mysite .
docker run -p 8000:8000 mysite

Writing custom templates

Some examples of custom templates.

• github.com/thibaudcolas/wagtail-tutorial-template
• github.com/torchbox/wagtail-news-template

You might get an error while trying to generate a custom template. This happens because the --template option attempts to parse the templates files in your custom template. To avoid this error, wrap the code in each of your template files with the {% verbatim %}{% endverbatim %} tag, like this:

{% 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 %}