Use .html.twig file extension in documentation instead of .html

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,20 +221,20 @@ 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]);
 
     $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::

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
 -----------------

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

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,44 +18,44 @@ 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``:
 
 .. 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
 ---------

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::
 

doc/functions/source.rst

@@ -5,15 +5,15 @@ 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
 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

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

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,17 +80,17 @@ 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
 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

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::

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::