Why does a Django child template that uses {% extends %} silently drop markup placed outside its {% block %} tags?

## How a child template is actually rendered The key to every inheritance surprise is one fact: **rendering a child template renders its parent**. When Django parses a template whose first tag is `{% extends 'base.html' %}`, the rest of the file becomes the extends node's contents. At render time that node: 1. loads the parent template, 2. collects every `{% block %}` found anywhere in the child — including blocks nested inside other tags — and registers them as overrides, 3. renders the parent, which outputs its own markup and, at each block, the most-derived override. The child's own markup is never rendered on its own. That single rule explains the list below. ## Trap 1: markup outside blocks vanishes ```django {% extends 'base.html' %} <p class="notice">Free cancellation until 24h before departure</p> {% block content %}...{% endblock %} ``` The `<p>` is not an error and not a warning; it is simply never output. The fix is to move it inside a block the parent renders, or to add a new block to the parent for it. ## Trap 2: a block inside `{% if %}` always overrides ```django {% if user.is_staff %} {% block banner %}Staff view{% endblock %} {% endif %} ``` The `{% if %}` sits outside every block, so it never runs; the `banner` block inside it is still collected in step 2. Every user sees "Staff view". Django's documentation states that blocks are evaluated first, so the override applies regardless of the truthiness of surrounding tags. The fix is to put the condition **inside** the block: ```django {% block banner %}{% if user.is_staff %}Staff view{% else %}{{ block.super }}{% endif %}{% endblock %} ``` ## Trap 3: variables set outside a block are invisible inside it A tag that stores its result with `as` (for example a tag that computes a value `as title`) placed outside a block in a child never executes, so the block sees no such variable. Compute it inside the block that uses it. ## Trap 4: each file loads its own tag libraries `{% load %}` works at **parse time**, per file. A library the parent loads is not available to the child's parser, so the child must load it too — and because `{% extends %}` must be the first template tag, the child's `{% load %}` goes **after** `extends`. A `{% load %}` before `extends` raises `TemplateSyntaxError` with the message that extends must be the first tag. ## Trap 5: parse-time errors worth recognising | Symptom | Cause | |---|---| | `{% extends ... %} must be the first tag` | a tag (often `{% load %}`) precedes `extends` | | `'block' tag with name '...' appears more than once` | two blocks with the same name in one file | | `'extends' cannot appear more than once` | a second `extends` in the same template | | `Invalid template name in 'extends' tag` | `extends` given a variable that resolved to an empty value | Duplicate block names are forbidden because a block works in both directions: it is a hole the file's own children can fill and the content that fills the hole in its parent. With two same-named blocks, the parent could not tell which one to use. ## Checklist for a child template - `{% extends %}` first; `{% load %}` for this file's tag libraries next. - Everything visible lives inside a block the parent renders. - Conditions go inside blocks, never around them. - Each block name appears once per file. Follow that and a child template becomes what it should be: a list of named overrides and nothing else.