From ab4e93af8b0322a142412642302c1da137600e47 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Thu, 9 May 2019 17:17:22 +0200
Subject: [PATCH] Update conditions.markdown

---
 source/_docs/scripts/conditions.markdown | 44 +++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown
index ed261f6c874..c34a5b9ba62 100644
--- a/source/_docs/scripts/conditions.markdown
+++ b/source/_docs/scripts/conditions.markdown
@@ -119,11 +119,53 @@ condition:
 ```
 
 ### {% linkable_title Sun condition %}
+#### Sun state condition
+The sun state can be used to test if the sun has set or risen.
 
-The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger].
+```yaml
+condition:
+    condition: state  # 'day' condition: from sunrise until sunset
+    entity_id: sun.sun
+    state: 'above_horizon'
+```
 
+```yaml
+condition:
+    condition: state  # from sunset until sunrise
+    entity_id: sun.sun
+    state: 'below_horizon'
+```
+
+#### Sun elevation condition
+The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night etc. when a trigger occurs.
+For an in depth explanation of sun elevation see [sun trigger][sun_trigger].
+
+```yaml
+condition:
+    condition: and  # 'twilight' condition: dusk and dawn, in typical locations
+    conditions:
+      - condition: template
+        value_template: '{{ states.sun.sun.attributes.elevation < 0 }}'
+      - condition: template
+        value_template: '{{ states.sun.sun.attributes.elevation > -6 }}'
+```
+
+```yaml
+condition:
+    condition: template  # 'night' condition: from dusk to dawn, in typical locations
+    value_template: '{{ states.sun.sun.attributes.elevation < -6 }}'
+```
+
+#### Sunset/sunrise condition
+The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger].
 [sun_trigger]: /docs/automation/trigger/#sun-trigger
 
+<p class='note warning'>
+The sunset/sunrise conditions do not work in locations inside the polar circles, and also not in locations with highly skewed local time zone.
+
+It is advised to use conditions evaluating the solar elevation instead of the before/after sunset/sunrise conditions.
+</p>
+
 ```yaml
 condition:
   condition: sun