Documentation: doc updates for nesting, reorganizing, fixes

This commit is contained in:
shamoon 2024-11-27 22:49:14 -08:00
parent 6d829bce79
commit e626274f34
No known key found for this signature in database
13 changed files with 132 additions and 92 deletions

View file

@ -0,0 +1,24 @@
---
title: Information Widgets
description: Homepage info widgets.
---
Information widgets are widgets that provide information about your system or environment and are displayed at the top of the homepage. You can find a list of all available info widgets under the [Info Widgets](../widgets/info/index.md) section.
Info widgets are defined in the widgets.yaml
Each widget has its own configuration options, which are detailed in the widget's documentation.
## Layout
Info widgets are displayed in the order they are defined in the `widgets.yaml` file. You can change the order by moving the widgets around in the file. However, some widgets (weather, search and datetime) are aligned to the right side of the screen which can affect the layout of the widgets.
## Adding A Link
You can add a link to an info widget such as the logo or text widgets by adding an `href` option, for example:
```yaml
logo:
href: https://example.com
target: _blank # Optional, can be set in settings
```

View file

@ -1,58 +0,0 @@
---
title: Service Widgets
description: Service Widget Configuration
---
Unless otherwise noted, URLs should not end with a `/` or other API path. Each widget will handle the path on its own.
Each service can have widgets attached to it (often matching the service type, but that's not forced).
In addition to the href of the service, you can also specify the target location in which to open that link. See [Link Target](settings.md#link-target) for more details.
Using Emby as an example, this is how you would attach the Emby service widget.
```yaml
- Emby:
icon: emby.png
href: http://emby.host.or.ip/
description: Movies & TV Shows
widget:
type: emby
url: http://emby.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
```
## Multiple Widgets
Each service can have multiple widgets attached to it, for example:
```yaml
- Emby:
icon: emby.png
href: http://emby.host.or.ip/
description: Movies & TV Shows
widgets:
- type: emby
url: http://emby.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
- type: uptimekuma
url: http://uptimekuma.host.or.ip:port
slug: statuspageslug
```
## Field Visibility
Each widget can optionally provide a list of which fields should be visible via the `fields` widget property. If no fields are specified, then all fields will be displayed. The `fields` property must be a valid YAML array of strings. As an example, here is the entry for Sonarr showing only a couple of fields.
**In all cases a widget will work and display all fields without specifying the `fields` property.**
```yaml
- Sonarr:
icon: sonarr.png
href: http://sonarr.host.or.ip
widget:
type: sonarr
fields: ["wanted", "queued"]
url: http://sonarr.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
```

View file

@ -21,6 +21,23 @@ Groups are defined as top-level array entries.
<img width="1038" alt="Service Groups" src="https://user-images.githubusercontent.com/82196/187040754-28065242-4534-4409-881c-93d1921c6141.png">
### Nested Groups
Groups can be nested by using the same format as the top-level groups.
```yaml
- Group A:
- Service A:
href: http://localhost/
- Group B:
- Service B:
href: http://localhost/
- Service C:
href: http://localhost/
```
## Services
Services are defined as array entries on groups,
@ -43,6 +60,60 @@ Services are defined as array entries on groups,
<img width="1038" alt="Service Services" src="https://user-images.githubusercontent.com/82196/187040763-038023a2-8bee-4d87-b5cc-13447e7365a4.png">
### Service Widgets
Each service can have widgets attached to it (often matching the service type, but that's not forced).
In addition to the href of the service, you can also specify the target location in which to open that link. See [Link Target](settings.md#link-target) for more details.
Using Emby as an example, this is how you would attach the Emby service widget.
```yaml
- Emby:
icon: emby.png
href: http://emby.host.or.ip/
description: Movies & TV Shows
widget:
type: emby
url: http://emby.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
```
#### Multiple Widgets
Each service can have multiple widgets attached to it, for example:
```yaml
- Emby:
icon: emby.png
href: http://emby.host.or.ip/
description: Movies & TV Shows
widgets:
- type: emby
url: http://emby.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
- type: uptimekuma
url: http://uptimekuma.host.or.ip:port
slug: statuspageslug
```
#### Field Visibility
Each widget can optionally provide a list of which fields should be visible via the `fields` widget property. If no fields are specified, then all fields will be displayed. The `fields` property must be a valid YAML array of strings. As an example, here is the entry for Sonarr showing only a couple of fields.
**In all cases a widget will work and display all fields without specifying the `fields` property.**
```yaml
- Sonarr:
icon: sonarr.png
href: http://sonarr.host.or.ip
widget:
type: sonarr
fields: ["wanted", "queued"]
url: http://sonarr.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
```
## Descriptions
Services may have descriptions,

View file

@ -137,6 +137,27 @@ layout:
columns: 3
```
### Nested Groups
If your services config has nested groups, you can apply settings to these groups by nesting them in the layout block
and using the same settings. For example
```yaml
layout:
Group A:
style: row
columns: 4
Group C:
style: row
columns: 2
Nested Group A:
style: row
columns: 2
Nested Group B:
style: row
columns: 2
```
### Headers
You can hide headers for each section in the layout as well by passing `header` as false, like so:
@ -348,12 +369,12 @@ This can also be set for individual services. Note setting this at the service l
## Providers
The `providers` section allows you to define shared API provider options and secrets. Currently this allows you to define your weather API keys in secret and is also the location of the Longhorn URL and credentials.
The `providers` section allows you to define shared API provider options and secrets.
```yaml
providers:
openweathermap: openweathermapapikey
weatherapi: weatherapiapikey
finnhub: yourfinnhubapikeyhere
longhorn:
url: https://longhorn.example.com
username: admin
@ -363,10 +384,10 @@ providers:
You can then pass `provider` instead of `apiKey` in your widget configuration.
```yaml
- weatherapi:
- openweathermap:
latitude: 50.449684
longitude: 30.525026
provider: weatherapi
provider: openweathermap
```
## Quick Launch