Fixed #29336 -- Doc'd circular template inheritance

2 files changed, 47 insertions, 0 deletions

diff --git a/docs/howto/overriding-templates.txt b/docs/howto/overriding-templates.txt
index 7faf972a3b..71eb14b0c4 100644
--- a/docs/howto/overriding-templates.txt
+++ b/docs/howto/overriding-templates.txt
@@ -97,3 +97,43 @@ then your directory structure will look like:
 
 With :setting:`APP_DIRS<TEMPLATES-APP_DIRS>` set to ``True``, the template
 loader will look in the app's templates directory and find the templates.
+
+.. _extending_an_overridden_template:
+
+Extending an overridden template
+================================
+
+With your template loaders configured, you can extend a template using the
+:ttag:`{% extends %}<extends>` template tag whilst at the same time overriding
+it. This can allow you to make small customizations without needing to
+reimplement the entire template.
+
+For example, you can use this technique to add a custom logo to the
+``admin/base_site.html`` template:
+
+    .. code-block:: html+django
+       :caption: templates/admin/base_site.html
+
+        {% extends "admin/base_site.html" %}
+
+        {% block branding %}
+            <img src="link/to/logo.png" alt="logo">
+            {{ block.super }}
+        {% endblock %}
+
+Key points to note:
+
+* The example creates a file at ``templates/admin/base_site.html`` that uses
+  the configured project-level ``templates`` directory to override
+  ``admin/base_site.html``.
+* The new template extends ``admin/base_site.html``, which is the same template
+  as is being overridden.
+* The template replaces just the ``branding`` block, adding a custom logo, and
+  using ``block.super`` to retain the prior content.
+* The rest of the template is inherited unchanged from
+  ``admin/base_site.html``.
+
+This technique works because the template loader does not consider the already
+loaded override template (at ``templates/admin/base_site.html``) when
+resolving the ``extends`` tag. Combined with ``block.super`` it is a powerful
+technique to make small customizations.
diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt
index 2a956f082c..d46a991c9e 100644
--- a/docs/ref/templates/language.txt
+++ b/docs/ref/templates/language.txt
@@ -407,6 +407,13 @@ Here are some tips for working with inheritance:
   not be automatically escaped (see the `next section`_), since it was
   already escaped, if necessary, in the parent template.
 
+* By using the same template name as you are inheriting from,
+  :ttag:`{% extends %}<extends>` can be used to inherit a template at the same
+  time as overriding it. Combined with ``{{ block.super }}``, this can be a
+  powerful way to make small customizations. See
+  :ref:`extending_an_overridden_template` in the *Overriding templates* How-to
+  for a full example.
+
 * Variables created outside of a :ttag:`{% block %}<block>` using the template
   tag ``as`` syntax can't be used inside the block. For example, this template
   doesn't render anything::