diff --git a/docs/defaults/guide.md b/docs/defaults/guide.md index 28329108..9e07063d 100644 --- a/docs/defaults/guide.md +++ b/docs/defaults/guide.md @@ -17,17 +17,9 @@ Special thanks to Magic815 for the overlay image inspiration and base template. Please consider [donating](https://github.com/sponsors/meisnate12) towards the project. -## Collection Defaults - -See the [Collection Defaults](collections.md) Page for more information on the specifics of the Collection Defaults. - -## Overlay Defaults - -See the [Overlay Defaults](overlays.md) Page for more information on the specifics of the Overlay Defaults. - ## Configurations -To run a default KometCollection or Overlay file you can simply add it to your `collection_files` (For Collection Files) +To run a default Kometa Collection or Overlay file you can simply add it to your `collection_files` (For Collection Files) or `overlay_files` (For Overlay Files) using `default` like so: ```yaml @@ -41,16 +33,60 @@ libraries: - default: ratings ``` -## Customizing Configs +## Customizing these defaults + +Configs can be customized using the `template_variables` attribute when calling the file. + +These template variables can be used to customize individual colelctions/overlays or the set as a whole. + +A given default may have variables that are specific to it, and may also leverage a common set of shared template variables. These lists are shown on each default file's wiki page. -Configs can be customized using the `template_variables` attribute when calling the file. These `template_variables` -will be given to every template call in the file which allows them to affect how that file runs. +## Customizing individual components -For collections, this example disables two keys, which will prevent those collections from being created. It also sets -the visibility of one of the keys so that it is visible on the library tab, the server owner's homescreen and shared -user's homescreens (assuming they server owner and/or the shared users have the library pinned to their homescreen) +Each default file uses "keys" to refer to the collections and overlays that it creates, and you can use those keys to modify the behavior of the defaults file. -For overlays, this example changes the ratings overlay to apply to episodes rather than shows. +For, example, the IMDB default creates three collections, each with their own "key": + +| Collection | Key | +|:--------------------|:----------| +| `IMDb Popular` | `popular` | +| `IMDb Top 250` | `top` | +| `IMDb Lowest Rated` | `lowest` | + +You use that key to customize the individual collection or overlay. + +This example disables two keys, which will prevent those collections from being created. It also sets +the visibility of one of the keys [`top`] so that it is visible on the library tab, the server owner's homescreen and shared +user's homescreens (assuming the server owner and/or the shared users have the library pinned to their homescreen) + +It also changes the resolution overlay to skip applying the overlay to 480p movies. + +The template variables in this example happen to be all shared template variables. + +```yaml +libraries: + Movies: + collection_files: + - default: imdb + template_variables: + use_popular: false # turn off the 'popular' key + use_lowest: false # turn off the 'lowest' key + visible_library_top: true # set visibilities for the 'top' key + visible_home_top: true + visible_shared_top: true + overlay_files: + - default: resolution + template_variables: + use_480p: false # turn off the '480p' key +``` + +## Customizing the set as a whole + +In addition to the keys, each default can be customized with other template variables that are not key-specific. + +This example uses a file-specific variable to change the order of all the IMDB chart collections to alphabetical by title and a shared variable to schedule these IMDB collections to be run only on Wednesdays. + +For the overlays, it uses a file-specific variable to disable all the "edition" overlays and a shared variable to align the overlay on the right side of the poster. ```yaml libraries: @@ -63,17 +99,33 @@ libraries: visible_library_top: true visible_home_top: true visible_shared_top: true + collection_order: alpha # file-specific variable sets sort order + schedule: weekly(wednesday) # shared variable sets schedule overlay_files: - - default: ratings + - default: ribbon template_variables: - builder_level: episode + use_480p: false + use_edition: false # file-specific variable hides editions + horizontal_align: right # shared variable sets alignment ``` -Each file has a page on the wiki showing the available `template_variables` for each file. For example the default -`default: ratings` has a page [here](overlays/ratings.md). +All of the default files are customized in this basic fashion. + +**NOTE: this `template_variable` system is specific to the defaults. If and when you start creating your own [collection](../files/collections.md) or [overlay](../files/overlays.md) files, you cannot use this `template_variables` setup unless you specifically write your files to implement it.** + +Each of these default files has a page on the wiki showing its keys, available `template_variables`, and default settings. For example, the default overlay `default: resolution` has a page [here](overlays/resolution.md). + +The shared template variables can be reviewed here for [Collections](collection_variables.md) and [Overlays](overlay_variables.md). These are also linked from each default file's wiki page. + +## Collection Defaults + +See the [Collection Defaults](collections.md) Page for more information on the specifics of the Collection Defaults. + +## Overlay Defaults + +See the [Overlay Defaults](overlays.md) Page for more information on the specifics of the Overlay Defaults. -**In addition to the defined `template_variables` almost all default Collection and Overlay files have access to their -respective [Collection](collection_variables.md)/[Overlay](overlay_variables.md) Shared Variables.** +# Example config using the defaults {% include-markdown "./example.md"