jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-14 21:06:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Advanced configuration: add subtitles (#31658)

Browse Source 
- To add more structure and improve readability
- Tiny style and grammar changes
- Add statement that included file must be valid YAML, and valid within the context of the file including it.
- Addresses feedback from #30542
This commit is contained in:
c0ffeeca7 2024-03-01 15:25:19 +01:00 committed by GitHub
parent 9ea9b51c32
commit fa52c5c0dd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 45 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
source/_docs/configuration/splitting_configuration.markdown
View File

@ -3,15 +3,23 @@ title: "Splitting up the configuration"
description: "Splitting the configuration.yaml into several files."
---
So you've been using Home Assistant for a while now and your `configuration.yaml` file brings people to tears or you simply want to start off with the distributed approach, here's how to split the `configuration.yaml` into more manageable (read: humanly readable) pieces.
So you've been using Home Assistant for a while now and your `configuration.yaml` file brings people to tears because it has become so large. Or, you simply want to start off with the distributed approach. Here's how to split the `configuration.yaml` into more manageable (read: human-readable) pieces.
First off, several community members have sanitized (read: without API keys/passwords etc) versions of their configurations available for viewing, you can see a list of them [here](/examples/#example-configurationyaml).
## Example configuration files for inspiration
As commenting code doesn't always happen, please read on for the details.
First off, several community members have sanitized (read: without API keys/passwords) versions of their configurations available for viewing. You can see a [list of example files here](/examples/#example-configurationyaml).
Now despite the logical assumption that the `configuration.yaml` will be replaced by this process it will in fact remain, albeit in a much less cluttered form.
As commenting code doesn't always happen, please read on to learn in detail how configuration files can be structured.
In this lighter version we will still need what could be called the core snippet:
## Analyzing the configuration files
In this section, we are going use some example configuration files and look at their structure and format in more detail.
Now you might think that the `configuration.yaml` will be replaced during the splitting process. However, it will in fact remain, albeit in a much less cluttered form.
### The core configuration file
In this lighter version, we will still need what could be called the core snippet:
```yaml
homeassistant:
@ -27,9 +35,11 @@ homeassistant:
customize: !include customize.yaml
```
### Indentation, includes, comments, and modularization
Note that each line after `homeassistant:` is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under `customize:`.
`!include customize.yaml` is the statement that tells Home Assistant to insert the contents of `customize.yaml` at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.
`!include customize.yaml` is the statement that tells Home Assistant to insert the parsed contents of `customize.yaml` at that point. The contents of the included file must be yaml data that is valid at the location it is included. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.
Now before we start splitting out the different components, let's look at the other integrations (in our example) that will stay in the base file:
@ -51,9 +61,20 @@ mqtt:
state_topic: "test/some_topic2"
```
As with the core snippet, indentation makes a difference. The integration headers (`mqtt:`) should be fully left aligned (aka no indent), and the key (`sensor:`) should be indented two (2) spaces. The list `-` under the key `sensor` should be indented another two (2) spaces followed by a single space. The `mqtt` sensor list contains two (2) configurations containing two (2) keys each.
As with the core snippet, indentation makes a difference:
While some of these integrations can technically be moved to a separate file they are so small or "one off's" where splitting them off is superfluous. Also, you'll notice the # symbol (hash/pound). This represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact.
- The integration headers (`mqtt:`) should be fully left aligned (aka no indent).
- The key (`sensor:`) should be indented two (2) spaces.
- The list `-` under the key `sensor` should be indented another two (2) spaces followed by a single space.
- The `mqtt` sensor list contains two (2) configurations, with two (2) keys each.
#### Comments
The # symbol (hash/pound) represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored by the software. It is for humans only. Comments allow breaking up files for readability, as well as turning off features while leaving the entry intact.
#### Modularization and granularity
While some of these integrations could technically be moved to a separate file, they are so small or "one off's" where splitting them off is superfluous.
Now, lets assume that a blank file has been created in the Home Assistant configuration directory for each of the following:
@ -68,7 +89,7 @@ customize.yaml
`automation.yaml` will hold all the automation integration details. `zone.yaml` will hold the zone integration details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of.
Inside the base configuration file add the following entries:
Inside the base configuration file, add the following entries:
```yaml
automation: !include automation.yaml
@ -78,9 +99,15 @@ switch: !include switch.yaml
device_tracker: !include device_tracker.yaml
```
Nesting `!include`s (having an `!include` within a file that is itself `!include`d) will also work.
#### Include statements and packages to split files
Some integrations support multiple top-level `!include`s, this includes integrations defining an IoT domain, e.g. `light`, `switch`, `sensor` as well as the `automation`, `script` and `template` integrations, if you give a different label to each one. Configuration for other integrations can instead be split up by using packages. To learn more about packages, see the [Packages](/docs/configuration/packages) page.
Nesting `!include` statements (having an `!include` within a file that is itself `!include`d) will also work.
Some integrations support multiple top-level `!include` statements. This includes integrations defining an IoT domain. For example, `light`, `switch`, or `sensor`; as well as the `automation`, `script`, and `template` integrations, if you give a different label to each one.
Configuration for other integrations can instead be split up by using packages. To learn more about packages, see the [Packages](/docs/configuration/packages) page.
#### Top level keys
Example of multiple top-level keys for the `light` platform.
@ -189,11 +216,11 @@ learn more about packages, see the [Packages](/docs/configuration/packages) page
That about wraps it up.
If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to our [Discord chat server][discord] and ask away.
If you have issues, checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to our [Discord chat server][discord] and ask away.
## Debugging configuration files
If you have many configuration files, Home Assistant provides a CLI that allows you to see how it interprets them, each installation type has its own section in the common-tasks about this:
If you have many configuration files, Home Assistant provides a CLI that allows you to see how it interprets them. Each installation type has its own section in the common-tasks about this:
- [Operating System](/common-tasks/os/#configuration-check)
- [Container](/common-tasks/container/#configuration-check)
@ -509,3 +536,8 @@ automation ui: !include automations.yaml
```
[discord]: https://discord.gg/c5DvZ4e
## Related topics
- [Example configuration files by the community](/examples/#example-configurationyaml)
- [Using packages to organize configuration files](/docs/configuration/packages)