add warning that using a backslash in front of a mustache expression disables it

diff --git a/docs/modules/ROOT/pages/templates.adoc b/docs/modules/ROOT/pages/templates.adoc
index 5d39f8b..823c9c0 100644 (file)
--- a/docs/modules/ROOT/pages/templates.adoc
+++ b/docs/modules/ROOT/pages/templates.adoc
@@ -3,8 +3,8 @@
 :idprefix:
 :idseparator: -
 
-Antora combines the Handlebars templates with the converted AsciiDoc content to make the pages in the site.
-These "`logic-less`" templates are mostly HTML with some special mustache tags sprinkled in where content is to be inserted.
+Antora combines the Handlebars templates with the converted AsciiDoc content and other UI model data to make the pages in the site.
+These "`logic-less`" templates are mostly HTML with some special mustache tags sprinkled in where content should be inserted.
 
 == What do the templates do?
 
@@ -12,9 +12,15 @@ The layout templates, which are stored in [.path]_src/layouts/_, provide the mai
 The partial templates, in [.path]_src/partials/_, fill in different regions of a page, such as the navigation and footer.
 
 The templates read from a model that's populated by Antora.
-Places in the template where the model is read are enclosed in `{{` and `}}` markers or `{{{` and `}}}`, aka mustaches (e.g., `+{{{page.title}}}+`).
-Double mustaches escape the content for HTML, whereas triple mustaches insert the content as is.
-When the `{{` is immediately followed by `>`, that invokes a partial and inserts the result (e.g., `+{{> head }}+`.
+The model can be accessed by enclosing path expressions in mustaches, which are `{{` and `}}` or `{{{` and `}}}` (e.g., `+{{{page.title}}}+`).
+The double mustaches escape the value for HTML, whereas triple mustaches insert the value as is.
+
+WARNING: If the mustaches are preceded by a backslash (e.g, `\{{`), the expression will be disabled.
+This often comes up when constructing URLs.
+To avoid this problem, you should use forward slashes in URLs instead of backslashes.
+
+When `{{` is immediately followed by `>`, that invokes a partial (from the partials directory) and inserts the result (e.g., `+{{> head}}+`.
+In other words, that's not a model reference like the other mustache expressions.
 
 === Template variables