# Cecil 9.18.0: a smarter configuration merge

[Cecil 9.18.0](https://github.com/Cecilapp/Cecil/releases/tag/9.18.0) reworks how your configuration is merged with the defaults and with the themes configuration. The goal: **define only what you want to change**, and get a predictable result.

### Layered configuration

The effective configuration is now built from layers, each one overriding the previous ones:

1. Cecil default configuration
2. themes configuration
3. site configuration (`cecil.yml`)
4. environment variables (`CECIL_*`) and command line options

Maps are merged key by key with the default ones: for example, adding a format to `layouts.translations.formats` no longer drops the built-in loaders. Themes can also override built-in defaults, such as default pages, generators and output formats.

A map can be enabled or disabled with a simple boolean, without losing its options:

```yaml
cache: false # same as `cache: {enabled: false}`
```

### Lists of values

When you define a list of values (e.g. `pages.ext`, `output.pagetypeformats` or `assets.images.responsive.widths`), it now **replaces** the default list. If a theme defines the same list, your values are **added** to the theme ones, as they can be required by the theme.

To **adjust** a default (or theme) list instead, use a map: `true` adds a value, `false` removes it.

```yaml
output:
  pagetypeformats:
    homepage:
      rss: true   # adds RSS
      atom: false # removes Atom
```

Output formats are merged by `name`, so `- {name: rss, filename: feed}` overrides only the `filename` of the RSS format.

### Deprecated options

Deprecated options are now checked before the configuration validation, and **all** of them are reported at once, with their source and the snippet to use instead:

````text
Deprecated configuration option(s) in "cecil.yml":
- Option `frontmatter` must be moved to:
  ```
  pages:
    frontmatter: yaml
  ```
- Option `pages.body.format` is deprecated and must be removed.
````

### New `enabled` test in templates

Since a disabled map is still a map, use the new [`enabled` test](/documentation/templates/reference/functions/#tests) to check an option in templates:

```twig
{% if config.cache is enabled %}
```

### Breaking changes

Please check your configuration before upgrading:

- A list of values defined in several `--config` files is now replaced by the last one, instead of being concatenated.
- A site can no longer clear a theme list by redefining it (`homepage: []`): remove each value with `false`.
- A theme configuration now overrides the built-in default pages, generators and output formats.
- `{% if config.cache %}` is true even when the cache is disabled with `cache: false`: use `{% if config.cache is enabled %}` instead.

Run `cecil show:config` to display the full effective configuration, defaults included.

See the [configuration documentation](/documentation/configuration/#priority) for more details, and [update Cecil](/download/#update) to get this release.