diff --git a/book/src/template_syntax.md b/book/src/template_syntax.md
index a794d3f66..9186d60be 100644
--- a/book/src/template_syntax.md
+++ b/book/src/template_syntax.md
@@ -587,3 +587,57 @@ You can optionally specify the name of the macro in `endmacro`:
 ```html
 {% macro heading(arg) %}<p>{{arg}}</p>{% endmacro heading %}
 ```
+
+You can also specify arguments by their name (as defined in the macro):
+
+```
+{% macro heading(arg, bold) %}
+
+<h1>{{arg}} <b>{{bold}}</b></h1>
+
+{% endmacro %}
+
+{% call heading(bold="something", arg="title") %}
+```
+
+You can use whitespace characters around `=`:
+
+```
+{% call heading(bold = "something", arg = "title") %}
+```
+
+You can mix named and non-named arguments when calling a macro:
+
+```
+{% call heading("title", bold="something") %}
+```
+
+However please note than named arguments must always come **last**.
+
+In this case, the named arguments will be passed to the related parameter and then the other
+arguments will be placed in what remains. Let's explain it in code:
+
+```
+{% macro heading(arg1, arg2, arg3, arg4) %}
+{% endmacro %}
+
+{% call heading("something", "b", arg4="ah", arg2="title") %}
+```
+
+First it'll be replaced like this:
+
+```
+arg1 =
+arg2 = "title"
+arg3 =
+arg4 = "ah"
+```
+
+Then `arg1` and `arg3` will be filled in the order of the arguments given to the macro call:
+
+```
+arg1 = "something"
+arg2 = "title"
+arg3 = "b"
+arg4 = "ah"
+```