From 03792f643f8fc0f5e556f1701775648a630a5d1b Mon Sep 17 00:00:00 2001
From: Pepperoni1337 <107676055+Pepperoni1337@users.noreply.github.com>
Date: Wed, 18 Dec 2024 08:13:12 +0100
Subject: [PATCH] Use .html.twig file extension in documentation instead of
 .html

---
 doc/api.rst               | 20 ++++++++++----------
 doc/deprecated.rst        |  4 ++--
 doc/functions/block.rst   |  4 ++--
 doc/functions/include.rst | 20 ++++++++++----------
 doc/functions/parent.rst  |  4 ++--
 doc/functions/source.rst  |  4 ++--
 doc/intro.rst             |  2 +-
 doc/recipes.rst           | 38 +++++++++++++++++++-------------------
 doc/sandbox.rst           |  2 +-
 doc/tags/deprecated.rst   | 10 +++++-----
 doc/tags/embed.rst        | 14 +++++++-------
 doc/tags/extends.rst      | 22 +++++++++++-----------
 doc/tags/include.rst      | 36 ++++++++++++++++++------------------
 doc/tags/macro.rst        | 12 ++++++------
 doc/tags/sandbox.rst      |  2 +-
 doc/tags/use.rst          | 28 ++++++++++++++--------------
 doc/templates.rst         | 12 ++++++------
 17 files changed, 117 insertions(+), 117 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index 18427713340..e091ee443e6 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -46,7 +46,7 @@ Rendering Templates
 To load a template from a Twig environment, call the ``load()`` method which
 returns a ``\Twig\TemplateWrapper`` instance::
 
-    $template = $twig->load('index.html');
+    $template = $twig->load('index.html.twig');
 
 To render the template with some variables, call the ``render()`` method::
 
@@ -58,7 +58,7 @@ To render the template with some variables, call the ``render()`` method::
 
 You can also load and render the template in one fell swoop::
 
-    echo $twig->render('index.html', ['the' => 'variables', 'go' => 'here']);
+    echo $twig->render('index.html.twig', ['the' => 'variables', 'go' => 'here']);
 
 If a template defines blocks, they can be rendered individually via the
 ``renderBlock()`` call::
@@ -177,7 +177,7 @@ methods act on the "main" namespace)::
 Namespaced templates can be accessed via the special
 ``@namespace_name/template_path`` notation::
 
-    $twig->render('@admin/index.html', []);
+    $twig->render('@admin/index.html.twig', []);
 
 ``\Twig\Loader\FilesystemLoader`` supports absolute and relative paths. Using relative
 paths is preferred as it makes the cache keys independent of the project root
@@ -198,11 +198,11 @@ the directory might be different from the one used on production servers)::
 array of strings bound to template names::
 
     $loader = new \Twig\Loader\ArrayLoader([
-        'index.html' => 'Hello {{ name }}!',
+        'index.html.twig' => 'Hello {{ name }}!',
     ]);
     $twig = new \Twig\Environment($loader);
 
-    echo $twig->render('index.html', ['name' => 'Fabien']);
+    echo $twig->render('index.html.twig', ['name' => 'Fabien']);
 
 This loader is very useful for unit testing. It can also be used for small
 projects where storing all templates in a single PHP file might make sense.
@@ -221,11 +221,11 @@ projects where storing all templates in a single PHP file might make sense.
 ``\Twig\Loader\ChainLoader`` delegates the loading of templates to other loaders::
 
     $loader1 = new \Twig\Loader\ArrayLoader([
-        'base.html' => '{% block content %}{% endblock %}',
+        'base.html.twig' => '{% block content %}{% endblock %}',
     ]);
     $loader2 = new \Twig\Loader\ArrayLoader([
-        'index.html' => '{% extends "base.html" %}{% block content %}Hello {{ name }}{% endblock %}',
-        'base.html'  => 'Will never be loaded',
+        'index.html.twig' => '{% extends "base.html.twig" %}{% block content %}Hello {{ name }}{% endblock %}',
+        'base.html.twig'  => 'Will never be loaded',
     ]);
 
     $loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);
@@ -233,8 +233,8 @@ projects where storing all templates in a single PHP file might make sense.
     $twig = new \Twig\Environment($loader);
 
 When looking for a template, Twig tries each loader in turn and returns as soon
-as the template is found. When rendering the ``index.html`` template from the
-above example, Twig will load it with ``$loader2`` but the ``base.html``
+as the template is found. When rendering the ``index.html.twig`` template from the
+above example, Twig will load it with ``$loader2`` but the ``base.html.twig``
 template will be loaded from ``$loader1``.
 
 .. note::
diff --git a/doc/deprecated.rst b/doc/deprecated.rst
index a6679a9eb37..c3d6c32ac6a 100644
--- a/doc/deprecated.rst
+++ b/doc/deprecated.rst
@@ -259,12 +259,12 @@ Sandbox
   Before::
 
     {% sandbox %}
-      {% include 'user_defined.twig' %}
+      {% include 'user_defined.html.twig' %}
     {% endsandbox %}
 
   After::
 
-    {{ include('user_defined.twig', sandboxed: true) }}
+    {{ include('user_defined.html.twig', sandboxed: true) }}
 
 Testing Utilities
 -----------------
diff --git a/doc/functions/block.rst b/doc/functions/block.rst
index ef8e5f4b614..acd13649283 100644
--- a/doc/functions/block.rst
+++ b/doc/functions/block.rst
@@ -17,7 +17,7 @@ template:
 
 .. code-block:: twig
 
-    {{ block("title", "common_blocks.twig") }}
+    {{ block("title", "common_blocks.html.twig") }}
 
 Use the ``defined`` test to check if a block exists in the context of the
 current template:
@@ -28,7 +28,7 @@ current template:
         ...
     {% endif %}
 
-    {% if block("footer", "common_blocks.twig") is defined %}
+    {% if block("footer", "common_blocks.html.twig") is defined %}
         ...
     {% endif %}
 
diff --git a/doc/functions/include.rst b/doc/functions/include.rst
index c5dfc9a9f6d..3314943921f 100644
--- a/doc/functions/include.rst
+++ b/doc/functions/include.rst
@@ -5,7 +5,7 @@ The ``include`` function returns the rendered content of a template:
 
 .. code-block:: twig
 
-    {{ include('template.html') }}
+    {{ include('template.html.twig') }}
     {{ include(some_var) }}
 
 Included templates have access to the variables of the active context.
@@ -18,8 +18,8 @@ additional variables:
 
 .. code-block:: twig
 
-    {# template.html will have access to the variables from the current context and the additional ones provided #}
-    {{ include('template.html', {name: 'Fabien'}) }}
+    {# template.html.twig will have access to the variables from the current context and the additional ones provided #}
+    {{ include('template.html.twig', {name: 'Fabien'}) }}
 
 You can disable access to the context by setting ``with_context`` to
 ``false``:
@@ -27,35 +27,35 @@ You can disable access to the context by setting ``with_context`` to
 .. code-block:: twig
 
     {# only the name variable will be accessible #}
-    {{ include('template.html', {name: 'Fabien'}, with_context = false) }}
+    {{ include('template.html.twig', {name: 'Fabien'}, with_context = false) }}
 
 .. code-block:: twig
 
     {# no variables will be accessible #}
-    {{ include('template.html', with_context = false) }}
+    {{ include('template.html.twig', with_context = false) }}
 
 And if the expression evaluates to a ``\Twig\Template`` or a
 ``\Twig\TemplateWrapper`` instance, Twig will use it directly::
 
     // {{ include(template) }}
 
-    $template = $twig->load('some_template.twig');
+    $template = $twig->load('some_template.html.twig');
 
-    $twig->display('template.twig', ['template' => $template]);
+    $twig->display('template.html.twig', ['template' => $template]);
 
 When you set the ``ignore_missing`` flag, Twig will return an empty string if
 the template does not exist:
 
 .. code-block:: twig
 
-    {{ include('sidebar.html', ignore_missing = true) }}
+    {{ include('sidebar.html.twig', ignore_missing = true) }}
 
 You can also provide a list of templates that are checked for existence before
 inclusion. The first template that exists will be rendered:
 
 .. code-block:: twig
 
-    {{ include(['page_detailed.html', 'page.html']) }}
+    {{ include(['page_detailed.html.twig', 'page.html.twig']) }}
 
 If ``ignore_missing`` is set, it will fall back to rendering nothing if none
 of the templates exist, otherwise it will throw an exception.
@@ -65,7 +65,7 @@ When including a template created by an end user, you should consider
 
 .. code-block:: twig
 
-    {{ include('page.html', sandboxed: true) }}
+    {{ include('page.html.twig', sandboxed: true) }}
 
 Arguments
 ---------
diff --git a/doc/functions/parent.rst b/doc/functions/parent.rst
index 158bac78b1e..c9acc8733cf 100644
--- a/doc/functions/parent.rst
+++ b/doc/functions/parent.rst
@@ -6,7 +6,7 @@ parent block when overriding a block by using the ``parent`` function:
 
 .. code-block:: html+twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
     {% block sidebar %}
         <h3>Table Of Contents</h3>
@@ -15,7 +15,7 @@ parent block when overriding a block by using the ``parent`` function:
     {% endblock %}
 
 The ``parent()`` call will return the content of the ``sidebar`` block as
-defined in the ``base.html`` template.
+defined in the ``base.html.twig`` template.
 
 .. seealso::
 
diff --git a/doc/functions/source.rst b/doc/functions/source.rst
index 080e2befe57..077ba91a402 100644
--- a/doc/functions/source.rst
+++ b/doc/functions/source.rst
@@ -5,7 +5,7 @@ The ``source`` function returns the content of a template without rendering it:
 
 .. code-block:: twig
 
-    {{ source('template.html') }}
+    {{ source('template.html.twig') }}
     {{ source(some_var) }}
 
 When you set the ``ignore_missing`` flag, Twig will return an empty string if
@@ -13,7 +13,7 @@ the template does not exist:
 
 .. code-block:: twig
 
-    {{ source('template.html', ignore_missing = true) }}
+    {{ source('template.html.twig', ignore_missing = true) }}
 
 The function uses the same template loaders as the ones used to include
 templates. So, if you are using the filesystem loader, the templates are looked
diff --git a/doc/intro.rst b/doc/intro.rst
index 5b0256f224c..7d01e5beb62 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -69,6 +69,6 @@ filesystem loader::
         'cache' => '/path/to/compilation_cache',
     ]);
 
-    echo $twig->render('index.html', ['name' => 'Fabien']);
+    echo $twig->render('index.html.twig', ['name' => 'Fabien']);
 
 .. _`SymfonyCasts Twig Tutorial`: https://symfonycasts.com/screencast/twig
diff --git a/doc/recipes.rst b/doc/recipes.rst
index 5144f211139..402279d1e63 100644
--- a/doc/recipes.rst
+++ b/doc/recipes.rst
@@ -66,7 +66,7 @@ the request is made via Ajax and choose the layout accordingly:
 
 .. code-block:: twig
 
-    {% extends request.ajax ? "base_ajax.html" : "base.html" %}
+    {% extends request.ajax ? "base_ajax.html.twig" : "base.html.twig" %}
 
     {% block content %}
         This is the content to be displayed.
@@ -80,9 +80,9 @@ instance, the name can depend on the value of a variable:
 
 .. code-block:: twig
 
-    {% include var ~ '_foo.html' %}
+    {% include var ~ '_foo.html.twig' %}
 
-If ``var`` evaluates to ``index``, the ``index_foo.html`` template will be
+If ``var`` evaluates to ``index``, the ``index_foo.html.twig`` template will be
 rendered.
 
 As a matter of fact, the template name can be any valid expression, such as
@@ -90,7 +90,7 @@ the following:
 
 .. code-block:: twig
 
-    {% include var|default('index') ~ '_foo.html' %}
+    {% include var|default('index') ~ '_foo.html.twig' %}
 
 Overriding a Template that also extends itself
 ----------------------------------------------
@@ -108,13 +108,13 @@ But how do you combine both: *replace* a template that also extends itself
 (aka a template in a directory further in the list)?
 
 Let's say that your templates are loaded from both ``.../templates/mysite``
-and ``.../templates/default`` in this order. The ``page.twig`` template,
+and ``.../templates/default`` in this order. The ``page.html.twig`` template,
 stored in ``.../templates/default`` reads as follows:
 
 .. code-block:: twig
 
-    {# page.twig #}
-    {% extends "layout.twig" %}
+    {# page.html.twig #}
+    {% extends "layout.html.twig" %}
 
     {% block content %}
     {% endblock %}
@@ -125,8 +125,8 @@ might be tempted to write the following:
 
 .. code-block:: twig
 
-    {# page.twig in .../templates/mysite #}
-    {% extends "page.twig" %} {# from .../templates/default #}
+    {# page.html.twig in .../templates/mysite #}
+    {% extends "page.html.twig" %} {# from .../templates/default #}
 
 However, this will not work as Twig will always load the template from
 ``.../templates/mysite``.
@@ -141,8 +141,8 @@ parent's full, unambiguous template path in the extends tag:
 
 .. code-block:: twig
 
-    {# page.twig in .../templates/mysite #}
-    {% extends "default/page.twig" %} {# from .../templates #}
+    {# page.html.twig in .../templates/mysite #}
+    {% extends "default/page.html.twig" %} {# from .../templates #}
 
 .. note::
 
@@ -393,15 +393,15 @@ First, let's create a temporary in-memory SQLite3 database to work with::
     $dbh->exec('CREATE TABLE templates (name STRING, source STRING, last_modified INTEGER)');
     $base = '{% block content %}{% endblock %}';
     $index = '
-    {% extends "base.twig" %}
+    {% extends "base.html.twig" %}
     {% block content %}Hello {{ name }}{% endblock %}
     ';
     $now = time();
-    $dbh->prepare('INSERT INTO templates (name, source, last_modified) VALUES (?, ?, ?)')->execute(['base.twig', $base, $now]);
-    $dbh->prepare('INSERT INTO templates (name, source, last_modified) VALUES (?, ?, ?)')->execute(['index.twig', $index, $now]);
+    $dbh->prepare('INSERT INTO templates (name, source, last_modified) VALUES (?, ?, ?)')->execute(['base.html.twig', $base, $now]);
+    $dbh->prepare('INSERT INTO templates (name, source, last_modified) VALUES (?, ?, ?)')->execute(['index.html.twig', $index, $now]);
 
 We have created a simple ``templates`` table that hosts two templates:
-``base.twig`` and ``index.twig``.
+``base.html.twig`` and ``index.html.twig``.
 
 Now, let's define a loader able to use this database::
 
@@ -456,7 +456,7 @@ Finally, here is an example on how you can use it::
     $loader = new DatabaseTwigLoader($dbh);
     $twig = new \Twig\Environment($loader);
 
-    echo $twig->render('index.twig', ['name' => 'Fabien']);
+    echo $twig->render('index.html.twig', ['name' => 'Fabien']);
 
 Using different Template Sources
 --------------------------------
@@ -474,15 +474,15 @@ logical name, and not the path from the filesystem::
 
     $loader1 = new DatabaseTwigLoader($dbh);
     $loader2 = new \Twig\Loader\ArrayLoader([
-        'base.twig' => '{% block content %}{% endblock %}',
+        'base.html.twig' => '{% block content %}{% endblock %}',
     ]);
     $loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);
 
     $twig = new \Twig\Environment($loader);
 
-    echo $twig->render('index.twig', ['name' => 'Fabien']);
+    echo $twig->render('index.html.twig', ['name' => 'Fabien']);
 
-Now that the ``base.twig`` templates is defined in an array loader, you can
+Now that the ``base.html.twig`` templates is defined in an array loader, you can
 remove it from the database, and everything else will still work as before.
 
 Loading a Template from a String
diff --git a/doc/sandbox.rst b/doc/sandbox.rst
index 7493fc3ea98..6e689583b89 100644
--- a/doc/sandbox.rst
+++ b/doc/sandbox.rst
@@ -61,7 +61,7 @@ function:
 
 .. code-block:: twig
 
-    {{ include('user.html', sandboxed: true) }}
+    {{ include('user.html.twig', sandboxed: true) }}
 
 You can sandbox all templates by passing ``true`` as the second argument of
 the extension constructor::
diff --git a/doc/tags/deprecated.rst b/doc/tags/deprecated.rst
index 811e88e3ff1..da5a0b7b92b 100644
--- a/doc/tags/deprecated.rst
+++ b/doc/tags/deprecated.rst
@@ -6,9 +6,9 @@ PHP function) where the ``deprecated`` tag is used in a template:
 
 .. code-block:: twig
 
-    {# base.twig #}
-    {% deprecated 'The "base.twig" template is deprecated, use "layout.twig" instead.' %}
-    {% extends 'layout.twig' %}
+    {# base.html.twig #}
+    {% deprecated 'The "base.html.twig" template is deprecated, use "layout.html.twig" instead.' %}
+    {% extends 'layout.html.twig' %}
 
 You can also deprecate a macro in the following way:
 
@@ -31,8 +31,8 @@ You can optionally add the package and the version that introduced the deprecati
 
 .. code-block:: twig
 
-    {% deprecated 'The "base.twig" template is deprecated, use "layout.twig" instead.' package='twig/twig' %}
-    {% deprecated 'The "base.twig" template is deprecated, use "layout.twig" instead.' package='twig/twig' version='3.11' %}
+    {% deprecated 'The "base.html.twig" template is deprecated, use "layout.html.twig" instead.' package='twig/twig' %}
+    {% deprecated 'The "base.html.twig" template is deprecated, use "layout.html.twig" instead.' package='twig/twig' version='3.11' %}
 
 .. note::
 
diff --git a/doc/tags/embed.rst b/doc/tags/embed.rst
index 232403a1128..17013b9b045 100644
--- a/doc/tags/embed.rst
+++ b/doc/tags/embed.rst
@@ -11,8 +11,8 @@ Think of an embedded template as a "micro layout skeleton".
 
 .. code-block:: twig
 
-    {% embed "teasers_skeleton.twig" %}
-        {# These blocks are defined in "teasers_skeleton.twig" #}
+    {% embed "teasers_skeleton.html.twig" %}
+        {# These blocks are defined in "teasers_skeleton.html.twig" #}
         {# and we override them right here:                    #}
         {% block left_teaser %}
             Some content for the left teaser box
@@ -111,14 +111,14 @@ code can live in a single base template, and the two different content structure
 let's call them "micro layouts" go into separate templates which are embedded
 as necessary:
 
-Page template ``page_1.twig``:
+Page template ``page_1.html.twig``:
 
 .. code-block:: twig
 
-    {% extends "layout_skeleton.twig" %}
+    {% extends "layout_skeleton.html.twig" %}
 
     {% block content %}
-        {% embed "vertical_boxes_skeleton.twig" %}
+        {% embed "vertical_boxes_skeleton.html.twig" %}
             {% block top %}
                 Some content for the top box
             {% endblock %}
@@ -129,7 +129,7 @@ Page template ``page_1.twig``:
         {% endembed %}
     {% endblock %}
 
-And here is the code for ``vertical_boxes_skeleton.twig``:
+And here is the code for ``vertical_boxes_skeleton.html.twig``:
 
 .. code-block:: html+twig
 
@@ -145,7 +145,7 @@ And here is the code for ``vertical_boxes_skeleton.twig``:
         {% endblock %}
     </div>
 
-The goal of the ``vertical_boxes_skeleton.twig`` template being to factor
+The goal of the ``vertical_boxes_skeleton.html.twig`` template being to factor
 out the HTML markup for the boxes.
 
 The ``embed`` tag takes the exact same arguments as the ``include`` tag:
diff --git a/doc/tags/extends.rst b/doc/tags/extends.rst
index 84d813e1742..5dc6ba0dd1a 100644
--- a/doc/tags/extends.rst
+++ b/doc/tags/extends.rst
@@ -9,7 +9,7 @@ The ``extends`` tag can be used to extend a template from another one.
     one extends tag called per rendering. However, Twig supports horizontal
     :doc:`reuse<use>`.
 
-Let's define a base template, ``base.html``, which defines a simple HTML
+Let's define a base template, ``base.html.twig``, which defines a simple HTML
 skeleton document:
 
 .. code-block:: html+twig
@@ -45,7 +45,7 @@ A child template might look like this:
 
 .. code-block:: html+twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
     {% block title %}Index{% endblock %}
     {% block head %}
@@ -156,16 +156,16 @@ instance, Twig will use it as the parent template::
 
     // {% extends layout %}
 
-    $layout = $twig->load('some_layout_template.twig');
+    $layout = $twig->load('some_layout_template.html.twig');
 
-    $twig->display('template.twig', ['layout' => $layout]);
+    $twig->display('template.html.twig', ['layout' => $layout]);
 
 You can also provide a list of templates that are checked for existence. The
 first template that exists will be used as a parent:
 
 .. code-block:: twig
 
-    {% extends ['layout.html', 'base_layout.html'] %}
+    {% extends ['layout.html.twig', 'base_layout.html.twig'] %}
 
 Conditional Inheritance
 -----------------------
@@ -175,10 +175,10 @@ possible to make the inheritance mechanism conditional:
 
 .. code-block:: twig
 
-    {% extends standalone ? "minimum.html" : "base.html" %}
+    {% extends standalone ? "minimum.html.twig" : "base.html.twig" %}
 
-In this example, the template will extend the "minimum.html" layout template
-if the ``standalone`` variable evaluates to ``true``, and "base.html"
+In this example, the template will extend the "minimum.html.twig" layout template
+if the ``standalone`` variable evaluates to ``true``, and "base.html.twig"
 otherwise.
 
 How do blocks work?
@@ -192,7 +192,7 @@ importantly, how it does not work:
 
 .. code-block:: html+twig
 
-    {# base.twig #}
+    {# base.html.twig #}
     {% for post in posts %}
         {% block post %}
             <h1>{{ post.title }}</h1>
@@ -206,8 +206,8 @@ to make it overridable by a child template:
 
 .. code-block:: html+twig
 
-    {# child.twig #}
-    {% extends "base.twig" %}
+    {# child.html.twig #}
+    {% extends "base.html.twig" %}
 
     {% block post %}
         <article>
diff --git a/doc/tags/include.rst b/doc/tags/include.rst
index c0a3c042592..3d2b2e0892b 100644
--- a/doc/tags/include.rst
+++ b/doc/tags/include.rst
@@ -6,9 +6,9 @@ of that file:
 
 .. code-block:: twig
 
-    {% include 'header.html' %}
+    {% include 'header.html.twig' %}
         Body
-    {% include 'footer.html' %}
+    {% include 'footer.html.twig' %}
 
 .. note::
 
@@ -25,17 +25,17 @@ of that file:
 
           {# Store a rendered template in a variable #}
           {% set content %}
-              {% include 'template.html' %}
+              {% include 'template.html.twig' %}
           {% endset %}
           {# vs #}
-          {% set content = include('template.html') %}
+          {% set content = include('template.html.twig') %}
 
           {# Apply filter on a rendered template #}
           {% apply upper %}
-              {% include 'template.html' %}
+              {% include 'template.html.twig' %}
           {% endapply %}
           {# vs #}
-          {{ include('template.html')|upper }}
+          {{ include('template.html.twig')|upper }}
 
     * The ``include`` function does not impose any specific order for
       arguments thanks to :ref:`named arguments <named-arguments>`.
@@ -49,23 +49,23 @@ You can add additional variables by passing them after the ``with`` keyword:
 
 .. code-block:: twig
 
-    {# template.html will have access to the variables from the current context and the additional ones provided #}
-    {% include 'template.html' with {'name': 'Fabien'} %}
+    {# template.html.twig will have access to the variables from the current context and the additional ones provided #}
+    {% include 'template.html.twig' with {'name': 'Fabien'} %}
 
     {% set vars = {'name': 'Fabien'} %}
-    {% include 'template.html' with vars %}
+    {% include 'template.html.twig' with vars %}
 
 You can disable access to the context by appending the ``only`` keyword:
 
 .. code-block:: twig
 
     {# only the name variable will be accessible #}
-    {% include 'template.html' with {'name': 'Fabien'} only %}
+    {% include 'template.html.twig' with {'name': 'Fabien'} only %}
 
 .. code-block:: twig
 
     {# no variables will be accessible #}
-    {% include 'template.html' only %}
+    {% include 'template.html.twig' only %}
 
 .. tip::
 
@@ -78,16 +78,16 @@ The template name can be any valid Twig expression:
 .. code-block:: twig
 
     {% include some_var %}
-    {% include ajax ? 'ajax.html' : 'not_ajax.html' %}
+    {% include ajax ? 'ajax.html.twig' : 'not_ajax.html.twig' %}
 
 And if the expression evaluates to a ``\Twig\Template`` or a
 ``\Twig\TemplateWrapper`` instance, Twig will use it directly::
 
     // {% include template %}
 
-    $template = $twig->load('some_template.twig');
+    $template = $twig->load('some_template.html.twig');
 
-    $twig->display('template.twig', ['template' => $template]);
+    $twig->display('template.html.twig', ['template' => $template]);
 
 You can mark an include with ``ignore missing`` in which case Twig will ignore
 the statement if the template to be included does not exist. It has to be
@@ -95,16 +95,16 @@ placed just after the template name. Here some valid examples:
 
 .. code-block:: twig
 
-    {% include 'sidebar.html' ignore missing %}
-    {% include 'sidebar.html' ignore missing with {'name': 'Fabien'} %}
-    {% include 'sidebar.html' ignore missing only %}
+    {% include 'sidebar.html.twig' ignore missing %}
+    {% include 'sidebar.html.twig' ignore missing with {'name': 'Fabien'} %}
+    {% include 'sidebar.html.twig' ignore missing only %}
 
 You can also provide a list of templates that are checked for existence before
 inclusion. The first template that exists will be included:
 
 .. code-block:: twig
 
-    {% include ['page_detailed.html', 'page.html'] %}
+    {% include ['page_detailed.html.twig', 'page.html.twig'] %}
 
 If ``ignore missing`` is given, it will fall back to rendering nothing if none
 of the templates exist, otherwise it will throw an exception.
diff --git a/doc/tags/macro.rst b/doc/tags/macro.rst
index 13c032915a9..ea173d5a877 100644
--- a/doc/tags/macro.rst
+++ b/doc/tags/macro.rst
@@ -49,9 +49,9 @@ tag:
 
 .. code-block:: twig
 
-    {% import "forms.twig" as forms %}
+    {% import "forms.html.twig" as forms %}
 
-The above ``import`` call imports the ``forms.twig`` file (which can contain
+The above ``import`` call imports the ``forms.html.twig`` file (which can contain
 only macros, or a template and some macros), and import the macros as
 attributes of the ``forms`` local variable.
 
@@ -69,7 +69,7 @@ via the ``from`` tag:
 
 .. code-block:: html+twig
 
-    {% from 'forms.twig' import input as input_field, textarea %}
+    {% from 'forms.html.twig' import input as input_field, textarea %}
 
     <p>{{ input_field('password', '', 'password') }}</p>
     <p>{{ input_field(name: 'password', type: 'password') }}</p>
@@ -82,7 +82,7 @@ via the ``from`` tag:
 
     .. code-block:: twig
 
-        {% from 'forms.twig' import input as include %}
+        {% from 'forms.html.twig' import input as include %}
 
         {# include refers to the macro and not to the built-in "include" function #}
         {{ include() }}
@@ -126,9 +126,9 @@ You can check if a macro is defined via the ``defined`` test:
 
 .. code-block:: twig
 
-    {% import "macros.twig" as macros %}
+    {% import "macros.html.twig" as macros %}
 
-    {% from "macros.twig" import hello %}
+    {% from "macros.html.twig" import hello %}
 
     {% if macros.hello is defined -%}
         OK
diff --git a/doc/tags/sandbox.rst b/doc/tags/sandbox.rst
index 57f1e5d1e17..b9b9a8dd6c6 100644
--- a/doc/tags/sandbox.rst
+++ b/doc/tags/sandbox.rst
@@ -12,7 +12,7 @@ template, when sandboxing is not enabled globally for the Twig environment:
 .. code-block:: twig
 
     {% sandbox %}
-        {% include 'user.html' %}
+        {% include 'user.html.twig' %}
     {% endsandbox %}
 
 .. warning::
diff --git a/doc/tags/use.rst b/doc/tags/use.rst
index 2aca6a01fb4..d26dc4f2cb4 100644
--- a/doc/tags/use.rst
+++ b/doc/tags/use.rst
@@ -14,7 +14,7 @@ debug:
 
 .. code-block:: twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
     {% block title %}{% endblock %}
     {% block content %}{% endblock %}
@@ -24,19 +24,19 @@ but without the associated complexity:
 
 .. code-block:: twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
-    {% use "blocks.html" %}
+    {% use "blocks.html.twig" %}
 
     {% block title %}{% endblock %}
     {% block content %}{% endblock %}
 
 The ``use`` statement tells Twig to import the blocks defined in
-``blocks.html`` into the current template (it's like macros, but for blocks):
+``blocks.html.twig`` into the current template (it's like macros, but for blocks):
 
 .. code-block:: twig
 
-    {# blocks.html #}
+    {# blocks.html.twig #}
     
     {% block sidebar %}{% endblock %}
 
@@ -46,7 +46,7 @@ imported blocks are not outputted automatically):
 
 .. code-block:: twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
     {% block sidebar %}{% endblock %}
     {% block title %}{% endblock %}
@@ -64,14 +64,14 @@ imported blocks are not outputted automatically):
     passed to the template, the template reference cannot be an expression.
 
 The main template can also override any imported block. If the template
-already defines the ``sidebar`` block, then the one defined in ``blocks.html``
+already defines the ``sidebar`` block, then the one defined in ``blocks.html.twig``
 is ignored. To avoid name conflicts, you can rename imported blocks:
 
 .. code-block:: twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
-    {% use "blocks.html" with sidebar as base_sidebar, title as base_title %}
+    {% use "blocks.html.twig" with sidebar as base_sidebar, title as base_title %}
 
     {% block sidebar %}{% endblock %}
     {% block title %}{% endblock %}
@@ -83,9 +83,9 @@ template:
 
 .. code-block:: twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
-    {% use "blocks.html" %}
+    {% use "blocks.html.twig" %}
 
     {% block sidebar %}
         {{ parent() }}
@@ -95,7 +95,7 @@ template:
     {% block content %}{% endblock %}
 
 In this example, ``parent()`` will correctly call the ``sidebar`` block from
-the ``blocks.html`` template.
+the ``blocks.html.twig`` template.
 
 .. tip::
 
@@ -103,9 +103,9 @@ the ``blocks.html`` template.
 
     .. code-block:: twig
 
-        {% extends "base.html" %}
+        {% extends "base.html.twig" %}
 
-        {% use "blocks.html" with sidebar as parent_sidebar %}
+        {% use "blocks.html.twig" with sidebar as parent_sidebar %}
 
         {% block sidebar %}
             {{ block('parent_sidebar') }}
diff --git a/doc/templates.rst b/doc/templates.rst
index 4235e6e9b51..18052f1c069 100644
--- a/doc/templates.rst
+++ b/doc/templates.rst
@@ -377,7 +377,7 @@ and return the rendered content of that template into the current one:
 
 .. code-block:: twig
 
-    {{ include('sidebar.html') }}
+    {{ include('sidebar.html.twig') }}
 
 By default, included templates have access to the same context as the template
 which includes them. This means that any variable defined in the main template
@@ -386,10 +386,10 @@ will be available in the included template too:
 .. code-block:: twig
 
     {% for box in boxes %}
-        {{ include('render_box.html') }}
+        {{ include('render_box.html.twig') }}
     {% endfor %}
 
-The included template ``render_box.html`` is able to access the ``box`` variable.
+The included template ``render_box.html.twig`` is able to access the ``box`` variable.
 
 The name of the template depends on the template loader. For instance, the
 ``\Twig\Loader\FilesystemLoader`` allows you to access other templates by giving the
@@ -397,7 +397,7 @@ filename. You can access templates in subdirectories with a slash:
 
 .. code-block:: twig
 
-    {{ include('sections/articles/sidebar.html') }}
+    {{ include('sections/articles/sidebar.html.twig') }}
 
 This behavior depends on the application embedding Twig.
 
@@ -411,7 +411,7 @@ override.
 
 It's easier to understand the concept by starting with an example.
 
-Let's define a base template, ``base.html``, which defines an HTML skeleton
+Let's define a base template, ``base.html.twig``, which defines an HTML skeleton
 document that might be used for a two-column page:
 
 .. code-block:: html+twig
@@ -443,7 +443,7 @@ A child template might look like this:
 
 .. code-block:: html+twig
 
-    {% extends "base.html" %}
+    {% extends "base.html.twig" %}
 
     {% block title %}Index{% endblock %}
     {% block head %}