diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 0905b2e59b8..e48a893e666 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -65,6 +65,39 @@ extensions: * [Loop Controls](https://jinja.palletsprojects.com/en/3.0.x/extensions/#loop-controls) (`break` and `continue`) +### Reusing Templates + +You can write reusable Jinja templates by adding them to a `custom_jinja` folder under your +configuration directory. All template files must have the `.jinja` extension and be less than 5MiB. +Templates in this folder will be loaded at startup. To reload the templates without +restarting Home Assistant, invoke the `homeassistant.reload_custom_jinja` service. + +Once the templates are loaded, Jinja [includes](https://jinja.palletsprojects.com/en/3.0.x/templates/#include) and [imports](https://jinja.palletsprojects.com/en/3.0.x/templates/#import) will work +using `config/custom_jinja` as the base directory. + +For example, you might define a macro in a template in `config/custom_jinja/formatter.jinja`: + +{% raw %} + +```text +{% macro format_entity(entity_id) %} +{{ state_attr(entity_id, 'friendly_name') }} - {{ states(entity_id) }} +{% endmacro %} +``` + +{% endraw %} + +In your automations, you could then reuse this macro by importing it: + +{% raw %} + +```text +{% from 'formatter.jinja' import format_entity %} +{{ format_entity('sensor.temperature') }} +``` + +{% endraw %} + ## Home Assistant template extensions Extensions allow templates to access all of the Home Assistant specific states and adds other convenience functions and filters. diff --git a/source/_integrations/homeassistant.markdown b/source/_integrations/homeassistant.markdown index 206711d1e10..58085970eec 100644 --- a/source/_integrations/homeassistant.markdown +++ b/source/_integrations/homeassistant.markdown @@ -29,11 +29,16 @@ Reload all YAML configuration that can be reloaded without restarting Home Assis It calls the `reload` service on all domains that have it available. Additionally, it reloads the core configuration (equivalent to calling -`homeassistant.reload_core_config`) and themes (`frontend.reload_themes`). +`homeassistant.reload_core_config`), themes (`frontend.reload_themes`), and custom Jinja (`homeassistant.reload_custom_jinja`). Prior to reloading, a basic configuration check is performed. If that fails, the reload will not be performed and will raise an error. +### Service `homeassistant.reload_custom_jinja` + +Reload all Jinja templates in the `config/custom_jinja` directory. Changes to these templates +will take effect the next time an importing template is rendered. + ### Service `homeassistant.reload_config_entry` Reloads an integration config entry.