Skip to content
Kuza Ndoto Academy

Template Inheritance

IntermediateChapter 3 · Page 10 of 234 min readUpdated 15 Nov 2026

Most websites repeat the same header, navigation bar and footer on every page. Template inheritance lets you write that layout once in a base template and have every other page fill in only the parts that change.

The idea: blocks

A base template defines named blocks, which are gaps that child templates can fill. A child template says which base it extends and then provides content for some or all of the blocks. Anything the child doesn't override keeps the base's default.

Step 1: Create a base template

Shared layouts usually go in a project-level templates/ folder. Make sure "DIRS": [BASE_DIR / "templates"] is in your TEMPLATES setting (see Django Templates).

templates/base.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{% block title %}Campus Events{% endblock %}</title>
</head>
<body>
  <header>
    <a href="{% url 'events:event_list' %}">Campus Events</a>
    <nav>
      <a href="{% url 'events:event_list' %}">All events</a>
      <a href="/admin/">Admin</a>
    </nav>
  </header>

  <main>
    {% block content %}{% endblock %}
  </main>

  <footer>
    {% block footer %}<p>Built by the Computer Science Club</p>{% endblock %}
  </footer>
</body>
</html>

This base defines three blocks: title, content and footer.

Step 2: Extend it in a child template

events/templates/events/event_list.html

{% extends "base.html" %}

{% block title %}Upcoming events | {{ block.super }}{% endblock %}

{% block content %}
  <h1>Upcoming events</h1>
  <ul>
    {% for event in events %}
      <li><a href="{% url 'events:event_detail' event.pk %}">{{ event.title }}</a></li>
    {% empty %}
      <li>No events yet.</li>
    {% endfor %}
  </ul>
{% endblock %}

When Django renders this page it starts from base.html, then swaps in the child's blocks. {{ block.super }} inserts the parent block's original content, so the browser tab reads:

Upcoming events | Campus Events
base.html header + nav {% block title %} {% block content %} {% block footer %} (default) event_list.html {% extends "base.html" %} Upcoming events | block.super <h1> and the list of events footer not overridden
Figure 1. The child only supplies content for the blocks it names; everything else, including the footer, comes from the base.

The child didn't override footer, so the club credit appears unchanged. The detail page works the same way:

events/templates/events/event_detail.html

{% extends "base.html" %}

{% block title %}{{ event.title }} | {{ block.super }}{% endblock %}

{% block content %}
  <h1>{{ event.title }}</h1>
  <p>{{ event.venue }}, {{ event.starts_at|date:"D j M Y, H:i" }}</p>
  {{ event.description|linebreaks }}
  <p><a href="{% url 'events:event_list' %}">Back to all events</a></p>
{% endblock %}

Rules to remember

  • {% extends %} must be the first tag in the child template.
  • In a child template, anything outside a {% block %} is ignored, because the base decides the layout.
  • Each block name may appear only once per template.
  • You can name the closing tag for readability: {% endblock content %}.
  • Inheritance can have several levels, e.g. base.html then events/base_events.html then event_list.html.
Common mistake

Spelling a block name differently in the child, such as {% block contents %} when the base says content. Django raises no error; your content simply never appears. If a page shows only the header and footer, compare block names first.

Reusing fragments with include

Inheritance shares the outer layout. For small pieces reused inside pages, such as an event "card", use {% include %}. Many developers start partial file names with an underscore.

events/templates/events/_event_card.html

<article class="event-card">
  <h2><a href="{% url 'events:event_detail' event.pk %}">{{ event.title }}</a></h2>
  <p>{{ event.venue }} · {{ event.starts_at|date:"j M, H:i" }}</p>
</article>

The list page can now loop over the card:

{% for event in events %}
  {% include "events/_event_card.html" %}
{% endfor %}

The included template sees the same variables as the page that includes it, so event is available. You can pass different values with with, for example {% include "events/_event_card.html" with event=featured %}, or add only to pass nothing else.

Showing messages in the base template

The base template is the perfect place for things every page needs, such as flash messages ("Event saved!") from Django's messages framework, which you'll use on the Django Forms page:

templates/base.html (inside <main>)

{% if messages %}
  <ul class="messages">
    {% for message in messages %}
      <li class="{{ message.tags }}">{{ message }}</li>
    {% endfor %}
  </ul>
{% endif %}
Tip

Add an empty {% block extra_head %}{% endblock %} inside <head> in your base. Pages that need an extra stylesheet or script can then add it without changing the base.

Key points

  • A base template defines the layout and named {% block %} areas.
  • Child templates start with {% extends "base.html" %} and override only the blocks they need.
  • {{ block.super }} keeps the parent's content and adds to it.
  • Use {% include %} for small reusable fragments like cards and menus.
Up next · TemplatesStatic FilesAdd CSS, JavaScript and images.
→

Tip: use the ← and → keys to move between pages.