Blueprints for template entities (#35057)

* First draft

* Better import instructions

* Revert a change

source/_data/glossary.yml

@@ -89,18 +89,18 @@
   link: /integrations/binary_sensor
 - term: Blueprint
   definition: >-
-    A blueprint is a script or automation configuration with certain parts
+    A blueprint is a script, automation or template entity configuration with certain parts
-    marked as configurable. This allows users to create multiple scripts or
+    marked as configurable. This allows users to create multiple scripts,
-    automations based on the same blueprint, with each having its own
+    automations or template entities based on the same blueprint, with each having its own
     configuration-specific settings. Blueprints are shared by the community on
     the [blueprints
     exchange](https://community.home-assistant.io/c/blueprints-exchange/53) in
     the forum.
   link: /docs/blueprint/
   excerpt: >-
-    A blueprint is a script or automation configuration with certain parts
+    A blueprint is a script, automation or template entity configuration with certain parts
-    marked as configurable. This allows users to create multiple scripts or
+    marked as configurable. This allows users to create multiple scripts,
-    automations based on the same blueprint, with each having its own
+    automations or template entities based on the same blueprint, with each having its own
     configuration-specific settings.
   aliases:
     - blueprints

source/_docs/blueprint.markdown

@@ -18,7 +18,7 @@ This section gives a high-level introduction to blueprints. To view a descriptio
 
 ## What is a blueprint?
 
-A blueprint is a {% term script %} or {% term automation %} configuration with certain parts marked as configurable. This allows you to create different scripts or automations based on the same blueprint.
+A blueprint is a {% term script %}, {% term automation %} or [template entity](/docs/integrations/template/) configuration with certain parts marked as configurable. This allows you to create different scripts, automations or template entities based on the same blueprint.
 
 Imagine you want to control lights based on motion. A blueprint provides the generic {% term automation %} framework, while letting you select one specific motion sensor as a {% term trigger %}, and the exact light to control. This blueprint makes it possible to create two automations. Each automation has their own configuration and act completely independently. Yet, they share some basic automation configuration so that you do not have to set this up every time.
 

source/_docs/blueprint/schema.markdown

@@ -57,7 +57,7 @@ description:
 domain:
   description: >
     The domain in which this blueprint is used. Currently, only
-    [`automation`](/docs/automation/yaml/) and `script` are supported.
+    [`automation`](/docs/automation/yaml/), `script` and [`template`](/docs/integrations/template/#using-blueprints) are supported.
   type: string
   required: true
 author:

source/_integrations/template.markdown

@@ -37,6 +37,8 @@ ha_config_flow: true
 related:
   - docs: /docs/configuration/
     title: Configuration file
+  - docs: /docs/blueprint/
+    title: About blueprints
 ---
 
 The `template` integration allows creating entities which derive their values from other data. This is done by specifying [templates](/docs/configuration/templating/) for properties of an entity, like the name or the state.
@@ -141,6 +143,15 @@ action:
   description: Define actions to be executed when the trigger fires. Optional. Variables set by the action script are available when evaluating entity templates. This can be used to interact with anything using actions, in particular actions with [response data](/docs/scripts/perform-actions#use-templates-to-handle-response-data). [See action documentation](/docs/automation/action).
   required: false
   type: list
+variables:
+  description: Key-value pairs of variable definitions which can be referenced and used in the templates below. Mostly used by blueprints.
+  required: false
+  type: map
+  keys:
+    "variable_name: value":
+      description: The variable name and corresponding value.
+      required: true
+      type: string
 sensor:
   description: List of sensors
   required: true
@@ -489,6 +500,46 @@ The same would apply to the `is_state()` function. You should replace {% raw %}`
 
 {% endraw %}
 
+## Using blueprints
+
+If you're just starting out and are not really familiar with templates, we recommend that you start with {% term blueprint %} template entities. These are template entities which are ready-made by the community and that you only need to configure.
+
+Each blueprint contains the "recipe" for creating a single template entity, but you can create multiple template entities based on the same blueprint.
+
+To create your first template entity based on a blueprint, open up your `configuration.yaml` file and add:
+
+```yaml
+# Example configuration.yaml template entity based on a blueprint located in config/blueprints/homeassistant/inverted_binary_sensor.yaml
+template:
+  - use_blueprint:
+      path: homeassistant/inverted_binary_sensor.yaml # relative to config/blueprints/template/
+      input:
+        reference_entity: binary_sensor.foo
+    name: Inverted foo
+    unique_id: inverted_foo
+```
+
+If you look at the blueprint definition, you will notice it has one input defined (`reference_entity`), which expects a `binary_sensor` entity ID. When you create a template entity based on that blueprint, you will have to tell it which of your `binary_sensor` entities it should use to fill that spot.
+
+### Importing blueprints
+
+Home Assistant can import blueprints from the Home Assistant forums, GitHub, and GitHub gists.
+
+1. To import a blueprint, first [find a blueprint you want to import][blueprint-forums].
+   - If you just want to practice importing, you can use this URL:
+
+      ```text
+      https://github.com/home-assistant/core/blob/dev/homeassistant/components/template/blueprints/inverted_binary_sensor.yaml
+      ```
+
+2. Download the file and place it under `config/blueprints/template/<source or author>/<blueprint name>.yaml`
+3. Use a config similar to the one above to create a new template entity based on the blueprint you just imported.
+4. Make sure to fill in all required inputs.
+
+The blueprint can now be used for creating template entities.
+
+[blueprint-forums]: /get-blueprints
+
 ## Examples
 
 In this section, you find some real-life examples of how to use template sensors.