document `lstrip_blocks`

diff --git a/docs/templates.rst b/docs/templates.rst
index 790b95e7c24908ff083291ad8e338ca6396b0685..ff7d5f738936da9d376232fa2e5fd118428d64e9 100644 (file)
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -156,9 +156,37 @@ In the default configuration, a single trailing newline is stripped if
 present, and whitespace is not further modified by the template engine. Each
 whitespace (spaces, tabs, newlines etc.) is returned unchanged.  If the
 application configures Jinja to `trim_blocks` the first newline after a a
-template tag is removed automatically (like in PHP).
+template tag is removed automatically (like in PHP). The `lstrip_blocks`
+option can also be set to strip tabs and spaces from the beginning of
+line to the start of a block. (Nothing will be stripped if there are
+other characters before the start of the block.)
+
+With both `trim_blocks` and `lstrip_blocks` enabled you can put block tags
+on their own lines, and the entire block line will be removed when
+rendered, preserving the whitespace of the contents.  For example,
+without the `trim_blocks` and `lstrip_blocks` options, this template::
+
+    <div>
+        {% if True %}
+            yay
+        {% endif %}
+    </div>
+
+gets rendered with blank lines inside the div::
+
+    <div>
+    
+            yay
+    
+    </div>
+
+But with both `trim_blocks` and `lstrip_blocks` enabled, the lines with the template blocks are removed while preserving the whitespace of the contents::
+    
+    <div>
+            yay
+    </div>
 
-But you can also strip whitespace in templates by hand.  If you put an minus
+You can also strip whitespace in templates by hand.  If you put an minus
 sign (``-``) to the start or end of an block (for example a for tag), a
 comment or variable expression you can remove the whitespaces after or before
 that block::