1 files changed, 181 insertions, 0 deletions
diff --git a/docs/switching.rst b/docs/switching.rst
new file mode 100644
index 0000000..caa35c3
--- /dev/null
+++ b/docs/switching.rst
@@ -0,0 +1,181 @@
+Switching From Other Template Engines
+=====================================
+
+This is a brief guide on some of the differences between Jinja syntax
+and other template languages. See :doc:`/templates` for a comprehensive
+guide to Jinja syntax and features.
+
+
+Django
+------
+
+If you have previously worked with Django templates, you should find
+Jinja very familiar. Many of the syntax elements look and work the same.
+However, Jinja provides some more syntax elements, and some work a bit
+differently.
+
+This section covers the template changes. The API, including extension
+support, is fundamentally different so it won't be covered here.
+
+Django supports using Jinja as its template engine, see
+https://docs.djangoproject.com/en/stable/topics/templates/#support-for-template-engines.
+
+
+Method Calls
+~~~~~~~~~~~~
+
+In Django, methods are called implicitly, without parentheses.
+
+.. code-block:: django
+
+    {% for page in user.get_created_pages %}
+        ...
+    {% endfor %}
+
+In Jinja, using parentheses is required for calls, like in Python. This
+allows you to pass variables to the method, which is not possible
+in Django. This syntax is also used for calling macros.
+
+.. code-block:: jinja
+
+    {% for page in user.get_created_pages() %}
+        ...
+    {% endfor %}
+
+
+Filter Arguments
+~~~~~~~~~~~~~~~~
+
+In Django, one literal value can be passed to a filter after a colon.
+
+.. code-block:: django
+
+    {{ items|join:", " }}
+
+In Jinja, filters can take any number of positional and keyword
+arguments in parentheses, like function calls. Arguments can also be
+variables instead of literal values.
+
+.. code-block:: jinja
+
+    {{ items|join(", ") }}
+
+
+Tests
+~~~~~
+
+In addition to filters, Jinja also has "tests" used with the ``is``
+operator. This operator is not the same as the Python operator.
+
+.. code-block:: jinja
+
+    {% if user.user_id is odd %}
+        {{ user.username|e }} is odd
+    {% else %}
+        hmm. {{ user.username|e }} looks pretty normal
+    {% endif %}
+
+Loops
+~~~~~
+
+In Django, the special variable for the loop context is called
+``forloop``, and the ``empty`` is used for no loop items.
+
+.. code-block:: django
+
+    {% for item in items %}
+        {{ item }}
+    {% empty %}
+        No items!
+    {% endfor %}
+
+In Jinja, the special variable for the loop context is called ``loop``,
+and the ``else`` block is used for no loop items.
+
+.. code-block:: jinja
+
+    {% for item in items %}
+        {{ loop.index}}. {{ item }}
+    {% else %}
+        No items!
+    {% endfor %}
+
+
+Cycle
+~~~~~
+
+In Django, the ``{% cycle %}`` can be used in a for loop to alternate
+between values per loop.
+
+.. code-block:: django
+
+    {% for user in users %}
+        <li class="{% cycle 'odd' 'even' %}">{{ user }}</li>
+    {% endfor %}
+
+In Jinja, the ``loop`` context has a ``cycle`` method.
+
+.. code-block:: jinja
+
+    {% for user in users %}
+        <li class="{{ loop.cycle('odd', 'even') }}">{{ user }}</li>
+    {% endfor %}
+
+A cycler can also be assigned to a variable and used outside or across
+loops with the ``cycle()`` global function.
+
+
+Mako
+----
+
+You can configure Jinja to look more like Mako:
+
+.. code-block:: python
+
+    env = Environment(
+        block_start_string="<%",
+        block_end_string="%>",
+        variable_start_string="${",
+        variable_end_string="}",
+        comment_start_string="<%doc>",
+        commend_end_string="</%doc>",
+        line_statement_prefix="%",
+        line_comment_prefix="##",
+    )
+
+With an environment configured like that, Jinja should be able to
+interpret a small subset of Mako templates without any changes.
+
+Jinja does not support embedded Python code, so you would have to move
+that out of the template. You could either process the data with the
+same code before rendering, or add a global function or filter to the
+Jinja environment.
+
+The syntax for defs (which are called macros in Jinja) and template
+inheritance is different too.
+
+The following Mako template:
+
+.. code-block:: mako
+
+    <%inherit file="layout.html" />
+    <%def name="title()">Page Title</%def>
+    <ul>
+    % for item in list:
+        <li>${item}</li>
+    % endfor
+    </ul>
+
+Looks like this in Jinja with the above configuration:
+
+.. code-block:: jinja
+
+    <% extends "layout.html" %>
+    <% block title %>Page Title<% endblock %>
+    <% block body %>
+    <ul>
+    % for item in list:
+        <li>${item}</li>
+    % endfor
+    </ul>
+    <% endblock %>