wip: Include-related docs (YAML and cli reference)

docs/behavior/include.md

@@ -0,0 +1,55 @@
+---
+id: include
+title: Include Behavior
+---
+
+## TODO
+
+- Terminology?
+  - include template
+  - configuration template
+- Include Schema
+- Merge Behavior & Precedence
+- Tips, such as using subdirectories in 'configs' which are not scanned for root YAML
+- Templates: Explain difference between Includes and Templates
+- Explain template contents: Schema is different.
+
+## Terminology
+
+- **Include Template**<br/>
+  A type of template that may *only* be included.
+
+- **Config Template**<br/>
+  A type of template that may *only* be used as a configuration file. It *cannot* be included. May
+  be created with the `config create` command.
+
+## Include YAML Schema
+
+Unlike configuration files, YAML that is included uses a simplified schema. Normally, in a
+configuration file, you have a structure like this:
+
+```yml
+radarr:
+  instance_name:
+    base_url: http://localhost:7878
+    api_key: the_key
+
+    custom_formats:
+      - trash_ids:
+          - id1
+          - id2
+```
+
+Since included YAML is only capable of adding information to *specific instance configurations*,
+they do not contain a service type (e.g. `radarr`) or an instance name (e.g. `instance_name`). If we
+convert the above example into a YAML file that may be included, it would look like this:
+
+```yml
+custom_formats:
+  - trash_ids:
+      - id1
+      - id2
+```
+
+You essentially start an include file as if it's everything under `instance_name`. We've left out
+`base_url` and `api_key` for reasons we get into later.

docs/cli/config/index.md

@@ -15,4 +15,4 @@ Commands used to perform configuration-related operations.
 ## Commands
 
 - [recyclarr config create](config-create.md)
-- [recyclarr config create](config-list.md)
+- [recyclarr config list](list/index.md)

docs/cli/config/list/config-list-local.md

@@ -0,0 +1,23 @@
+---
+id: local
+title: recyclarr config list local
+---
+
+## Usage
+
+```js
+recyclarr config list local
+```
+
+## Description
+
+Lists all configuration files according to the [default YAML file][1] locations.
+
+[1]: /file-structure.md#default-yaml
+
+## Command Line Examples
+
+```bash
+# List only local config files
+recyclarr config list local
+```

docs/cli/config/list/config-list-templates.md

@@ -0,0 +1,36 @@
+---
+id: templates
+title: recyclarr config list templates
+---
+
+## Usage
+
+```js
+recyclarr config list templates [OPTIONS]
+```
+
+## Description
+
+Lists available template configuration files in the [Trash Guides repo][1].
+
+[1]: https://trash-guides.info/Recyclarr/recyclarr-configs/
+
+## Options
+
+### `-i|--includes` {#include}
+
+If specified, this command lists the IDs of all include templates. In contrast to configuration
+templates, which are only usable with the `config create` command, include templates may only be
+included with the [`include` property][include].
+
+[include]: /yaml/config-reference/include.md
+
+## Command Line Examples
+
+```bash
+# List available configuration templates
+recyclarr config list templates
+
+# List available include templates
+recyclarr config list templates --includes
+```

docs/cli/config/list/index.md

@@ -0,0 +1,18 @@
+---
+title: recyclarr config list
+---
+
+## Usage
+
+```js
+recyclarr config list <COMMAND>
+```
+
+## Description
+
+Commands used to perform configuration-related operations.
+
+## Commands
+
+- [recyclarr config list local](config-list-local.md)
+- [recyclarr config list templates](config-list-templates.md)

docs/yaml/config-reference/include.md

@@ -0,0 +1,98 @@
+---
+id: include
+title: Include
+sidebar_position: 6
+---
+
+| Service     |                        Supported                         |
+| ----------- | :------------------------------------------------------: |
+| Sonarr (v3) | <icon icon="mdi:check-bold" height="24" color="green" /> |
+| Sonarr (v4) | <icon icon="mdi:check-bold" height="24" color="green" /> |
+| Radarr      | <icon icon="mdi:check-bold" height="24" color="green" /> |
+
+```yml
+# See "Basic Setup" for `service_type` and `instance_name`
+service_type:
+  instance_name:
+    # Include Configuration
+    include:
+      - template: uhd-bluray-web
+      - config: includes/my-config.yml
+```
+
+YAML includes are a mechanism to support reusable configurations. Including YAML is the process of
+taking the contents of one YAML file and merging it into the source (root) YAML.
+
+:::info Recommended Reading
+
+For more details about how includes and merging work, see the [Include Behavior] page.
+
+[Include Behavior]: /behavior/include.md
+
+:::
+
+## `include` {#service-type}
+
+**Optional.** *Default: Nothing is included.*
+
+A sequence of include directives. There are multiple types of include directives. Each type will
+have one or more properties. Use the appropriate include directive for the kind of inclusion you
+wish to perform. The sequence may contain a mixture of different include directive types.
+
+The sections that follow correlate to types of include directives.
+
+## Config Includes
+
+Use this directive to include YAML files on your local filesystem.
+
+### `config`
+
+**Required.**
+
+An absolute or relative path to the YAML file you wish to include. Relative paths start at the
+`configs` directory inside the [app data directory][appdata]
+
+[appdata]: /file-structure.md#appdata-directory
+
+### Examples
+
+```yml
+include:
+  # An absolute include path
+  - config: /home/john/my-config.yml
+
+  # A relative include path
+  # Equivalent absolute path is (on Linux):
+  #   /home/john/.config/recyclarr/configs/include/my-config.yml
+  - config: my-config.yml
+```
+
+## Template Includes
+
+Utilize the [Configuration Templates][templates] repository to include YAML files.
+
+[templates]: https://github.com/recyclarr/config-templates
+
+### `template`
+
+**Required.**
+
+The ID of an **include template**. The corresponding YAML in the configuration templates repository
+will be included. IDs matching include templates from a non-matching service type are not allowed
+(e.g. trying to include a Sonarr template inside a Radarr config).
+
+:::tip
+
+To get a list of eligible **include templates**, see the [`config list templates` command][list].
+
+[list]: /cli/config/list/config-list-templates.md#include
+
+:::
+
+### Examples
+
+```yml
+include:
+  # Includes a template YAML with this ID
+  - template: TBD
+```

docs/yaml/config-reference/index.md

@@ -62,3 +62,4 @@ Add this comment to the top of your YAML file:
 - [Quality Definition](quality-definition.md)
 - [Quality Profiles](quality-profiles.md)
 - [Release Profiles](release-profiles.md)
+- [Include](include.md)