diff --git a/docs/_include-templates-dir.md b/docs/_include-templates-dir.md new file mode 100644 index 0000000..1f1295c --- /dev/null +++ b/docs/_include-templates-dir.md @@ -0,0 +1,34 @@ +A directory named `includes` exists under the application data directory where local [include +templates][configdirective] may be placed. Any relative paths to include templates will start at +this directory. + +For example, if I have the following include directive in a configuration file named `foo.yml`: + +```yml +include: + - config: bar/reusable.yml +``` + +The expected file structure of my `includes` directory would be visualized as follows: + +```txt +. +├── configs/ +│ └── foo.yml +└── includes/ + └── bar/ + └── reusable.yml +``` + +For more information about include templates, see the respective [behaviors page][include]. + +:::caution + +Configuration files (non-includes) should *not* be placed here; use the [`configs`][configsdir] +directory for those. + +::: + +[include]: /yaml/config-reference/include.md +[configdirective]: /yaml/config-reference/include.md#config +[configsdir]: /file-structure.md#config-directory diff --git a/docs/behavior/include.md b/docs/behavior/include.md index d86d606..2d32d20 100644 --- a/docs/behavior/include.md +++ b/docs/behavior/include.md @@ -393,33 +393,6 @@ custom_formats: ### Include File Structure {#file-structure} -This section covers the currently recommended file structure for local YAML includes. +import IncludeDirectory from '../_include-templates-dir.md' -Recyclarr does not recursively scan for configuration YAML files in the [`configs` -subdirectory][configdir]. This means that you can structure local include YAML files into -subdirectories inside `configs`. This allows the convenient usage of relative paths when using the -[`config` include directive][configdirective]. - -As an example, consider this file structure: - -```txt -. -└── configs/ - ├── includes/ - │ └── reusable.yml - └── my-config.yml -``` - -And the `my-config.yml` file has the following include directives: - -```yml -include: - - config: includes/reusable.yml -``` - -Because we have our includes within the `configs` directory, we can easily access them with a -relative path. And since those includes are under a subdirectory, Recyclarr will not scan them and -treat them as top-level configuration YAML files. - -[configdir]: /file-structure.md#config-directory -[configdirective]: /yaml/config-reference/include.md#config + diff --git a/docs/file-structure.md b/docs/file-structure.md index c30d3a8..2314671 100644 --- a/docs/file-structure.md +++ b/docs/file-structure.md @@ -48,7 +48,16 @@ really have an easy way to specify custom CLI arguments. The following requireme `--config` command line argument. This behavior is non-recursive; meaning if you place YAML files in subdirectories under `configs/`, they will not be loaded. - The names of the files are unimportant and can be whatever you want. -- [Include templates][inc] should *not* be placed in this directory; only real configuration files - are supported here. -[inc]: /yaml/config-reference/include.md +:::caution + +Include templates should *not* be placed here; use the [`includes`](#include-directory) directory +instead. + +::: + +## Include Templates Directory {#include-directory} + +import IncludeDirectory from './_include-templates-dir.md' + + diff --git a/docs/yaml/config-reference/include.md b/docs/yaml/config-reference/include.md index 75688aa..a6c6fb4 100644 --- a/docs/yaml/config-reference/include.md +++ b/docs/yaml/config-reference/include.md @@ -48,10 +48,10 @@ Use this directive to include YAML files on your local filesystem. **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] +An absolute or relative path to the YAML file you wish to include. If relative paths are used, see +the [app data directory][appdata] page for where those files should be located. -[appdata]: /file-structure.md#appdata-directory +[appdata]: /file-structure.md#include-directory ### Examples