Reworked templating documentation is now live, feedback welcome!

[frenck (Franck Nijhof)]

Oh hi there

TL;DR, we have new and extensive template documentation! Take a look here: Templating - Home Assistant

Templating is the corner of Home Assistant that trips people up most often. Someone wants to show the actual temperature in a notification, or add a small calculation to an automation, and the docs feel like homework. That is not how it should feel.

So these past weeks I have been reworking the templating documentation with one goal in mind: make it more approachable. Clear explanations, real examples, and a structure you can actually navigate. Whether you are writing your first template or you have been answering template questions in this forum for years, we want these docs to work for you.

The changes are live on home-assistant.io right now. This is a first pass, and the best docs come from real people using them and telling us what is off. If something is confusing, wrong, or missing, I would love to hear about it.

What is new

• Every template function, filter, and test has its own page. All 200 of them, in their own dedicated pages, each with a plain-language intro, parameters, examples with expected output, common gotchas, and related functions.

• 14 learning pages that walk you through templating concepts step by step: introduction, where to use templates, syntax, loops and conditions, types and conversion, working with states, dates and times, Python methods, common patterns, debugging, error messages, templates in YAML, custom templates, and more.

• 2 step-by-step tutorials: one that builds a real automation (a daily low battery notification that tells you which devices need new batteries, naming the device and the area it is in), and one that creates a real template sensor (an average home temperature sensor you can drop on a dashboard or use in automations). These are not throwaway showcases, they are things you can use directly after finishing the tutorial.

• An error messages index page that lists common template errors verbatim with plain-language fixes, so you can Google the exact error string and land on a page that actually helps.

• A dedicated Templating section in the docs sidebar, separate from advanced configuration, so it has its own home.

• Support bridges at the bottom of every page that point to Discord, the forum, our subreddit, and mention that AI assistants can also help write or fix templates.

• Templates in code blocks are now interactive, site-wide. Template syntax gets proper highlighting (filters, functions, strings, numbers). Hover over any function name in an example and you see a tooltip with its description; click and you land on the function reference page. Hover over a parameter name and you see the parameter’s description. This works on every template example across the whole site, not only inside the templating docs. It also works when templates appear inside YAML examples, which is how most people actually meet them.

• A new way to show templates and their results. Every example renders as a clean input block followed by the output it produces, with a visual arrow connecting them. No guessing what the template will do, you see the exact result right there.

What I tried to do differently

• Language a broader audience can follow. The docs are written so someone new to Home Assistant can read along, without losing the precision experienced users rely on. Concepts come in plain words first, technical terminology alongside when it helps.

• No jargon gatekeeping. Dropped words like “advanced”, “simple”, “just”, “complex”, “tricky”. Explained terms like “iterable”, “generator”, and “callable” when they have to appear.

• Practical examples, not contrived ones. Realistic entity IDs, realistic output values, things people actually want to do.

• Better cross-linking. Function pages link to the learning pages that cover their category. Learning pages link to the specific functions they mention. Control structures in prose link back to the loops and conditions page.

• Searchable errors. Error messages get their own page because when something breaks at 11pm, you paste the error into Google.

A wider goal. One of the things we want to focus on this year is making Home Assistant feel more approachable. Templating is the corner that works against that feeling the most, it is where a lot of people hit the wall of “this is too technical for me”. Clearer, more structured docs help this corner feel more approachable for more of us. They also help the AI assistants people increasingly turn to for help. If you paste a template error into ChatGPT or Claude, we want those tools to give good, current answers, which means these docs need to be the kind of reference they cite.

What I am asking for

Please skim whatever looks interesting to you and let me know:

1. Does the learning flow make sense if you are new to templates?
2. Is the language accessible, or do I still use terms that need explaining?
3. Any function pages where the description is wrong, confusing, or missing important context?
4. Any common error messages missing from the error index?
5. Any patterns you use all the time that are missing from the cookbook?
6. Anything else that bugs you or could be better?

I am especially interested in hearing from people who have helped others with templates in this forum or on Discord, because you see the pain points up close.

Contribute examples

Examples are what makes these docs come alive. If you have a template pattern you reach for all the time and it is not in the cookbook, or a realistic example for a specific function that you think would help others land faster, I would love to hear about it. Drop it in a reply here, or open a PR against the docs yourself. Small contributions like a single extra example on a function page are very welcome.

Links

The pages I would love you to look at:

• New Templating home: Templating - Home Assistant
• Function reference: Template functions - Home Assistant
• Error messages page: Template error messages and fixes - Home Assistant

Thanks for taking a look. Every comment, correction, and suggestion makes the next round better.

…/Frenck

                       

[slimak]

I really like the idea, the documentation looks good in terms of functionality.

I think I spotted an error in the battery tutorial, the code needs namespace, e.g.

{% set low = namespace(v=[]) %}
{% for sensor in states.sensor
   | selectattr('attributes.device_class', 'eq', 'battery')
   | rejectattr('state', 'in', ['unknown', 'unavailable']) %}
  {% if sensor.state | float(100) < 20 %}
    {% set low.v = low.v + [device_name(sensor.entity_id)] %}
  {% endif %}
{% endfor %}
{{ low.v }}

[frenck (Franck Nijhof)]

Thanks! Well spotted, make a PR to address it here: Fix template example in low batteries tutorial by frenck · Pull Request #44513 · home-assistant/home-assistant.io · GitHub

…/Frenck

                       

[slimak]

Also, Loops and Conditions, The do statement:

{% set numbers = [] %}
{% do numbers.append(1) %}
{% do numbers.append(2) %}
{% do numbers.append(3) %}
{{ numbers }}

It will error out (at least in the Developer Tools): “access to attribute ‘append’ of ‘list’ object is unsafe”. I’ve never seen the do statement used by anyone in Home Assistant, so I’m actually curious of an example.

[boheme61 (JC)]

It’s Late here TLDR Well first Page Looked Good , short and straight forward, the structure of the page Great.
Maybe i fill in more here, when im through it all

Yeah, i know im not a “Green” , but i still always have a “simple” way of looking at things

Nice with an easy readable Functions List
Even syntax and Python Methods , very easy to understand

Overall, You can always fallback as a Teacher … After you finished this cumbersome and valuable task !

[frenck (Franck Nijhof)]

Thanks! Golden catches! While looking for more, I noticed it can be fixed even better…

Fix broken examples using sandboxed mutation methods

So, that should cover all occurances while also documenting a quirk!

…/Frenck

                       

[Mahko_Mahko]

Amazingly better.

A few typo’s here:

Template functions

Something funny going on there with the text getting truncated and shifted to the function name?

I also think this page might be a bit more digestible if either the categories were collapsed or if they were each presented at the top or in the sidebar so you can see all categories before you get searching.

[frenck (Franck Nijhof)]

Thanks! That one was reported on quite a few places. It is a technical error though, as those pages are generated.

I’ve opened up a pull request to fix that one here: Fix and DRY up template function category listing pages by frenck · Pull Request #44518 · home-assistant/home-assistant.io · GitHub

Thanks for reporting as well <3!

…/Frenck

                       

Blogging my personal ramblings at frenck.dev

[frenck (Franck Nijhof)]

Hehe good point, added a single line TL;DR in the top

Have an amazing easter!

…/Frenck

                       

Blogging my personal ramblings at frenck.dev

[slimak]

After reading some more pages: great documentation, really, and much needed. Plenty of examples specific to Home Assistant, which are missing from the general Jinja docs.
No more pain trying to remember what “map” actually does and how it interfaces with Home Assistant structures!

I think I found another problem in the “Python Methods” chapter: the string method links (purple) point to filters.

• the string method count points to filter count, which takes no arguments.
• the string method format points to filter format, which uses completely different arguments.

[Mahko_Mahko]

@Mahko_Mahko

I also think this page might be a bit more digestible if either the categories were collapsed or if they were each presented at the top or in the sidebar so you can see all categories before you get searching.

So a bit more of this kind of side navigation could be nice.

[boheme61 (JC)]

Sorry im not the right person to look for typos or errors , typos i pretty easy skip/ignore if i understand the context … didn’t even notice those in Functions, even thou i clicked a dozen

[HappyCadaver (Rick Furtado)]

Incredible improvement Frenck, I tripped into it from the dev templates page and thought my link was broken. The readability is leaps and bounds better.

Landing page: none of the links on the right hand side work.

And the reason I was there in the first place… the states() function page seems to suggest that it can be used as a filter or a function…

Also there is only one parameter and there should be 3. This example even shows the unit of measurement being added after the template (hard coded) which seems all kinds of wrong to me considering that it’s otherwise accurately provided.

[frenck (Franck Nijhof)]

Fixing the broken TOC links in this PR: Exclude landing page card titles from 'On this page' TOC by frenck · Pull Request #44519 · home-assistant/home-assistant.io · GitHub

Will look at the other comments next.

…/Frenck

                       

Blogging my personal ramblings at frenck.dev

[Didgeridrew]

@HappyCadaver

the states() function page seems to suggest that it can be used as a filter or a function…

It can be:

[frenck (Franck Nijhof)]

Fix for the missing parameters are pending in a pull request here: Document missing rounded and with_unit parameters for states() by frenck · Pull Request #44520 · home-assistant/home-assistant.io · GitHub

As pointed out by @Didgeridrew, it actually can be used as a filter

…/Frenck

                       

Blogging my personal ramblings at frenck.dev

[HappyCadaver (Rick Furtado)]

Right, thanks. I had not used it that way previously but my quick test was a bad implementation, I tried it on a generator object

[frenck (Franck Nijhof)]

Luckly we have that stuff documented now as well

…/Frenck

[123 (Taras)]

FWIW, a common usage of states as a filter is with map.

Example

How many lights are on in the Kitchen?

{{ area_entities('Kitchen') 
  | select('match', 'light')
  | map('states')
  | select('eq', 'on')
  | list | count }}