From e626274f3457ad4f7eabe930bb76e4ee8da95f15 Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Wed, 27 Nov 2024 22:49:14 -0800 Subject: [PATCH] Documentation: doc updates for nesting, reorganizing, fixes --- docs/configs/info-widgets.md | 24 +++++++++++ docs/configs/service-widgets.md | 58 ------------------------- docs/configs/services.md | 71 +++++++++++++++++++++++++++++++ docs/configs/settings.md | 29 +++++++++++-- docs/troubleshooting/index.md | 2 +- docs/widgets/authoring/proxies.md | 2 +- docs/widgets/index.md | 4 ++ docs/widgets/info/openmeteo.md | 2 +- docs/widgets/info/weather.md | 22 ---------- mkdocs.yml | 4 +- src/skeleton/services.yaml | 2 +- src/skeleton/settings.yaml | 2 +- src/skeleton/widgets.yaml | 2 +- 13 files changed, 132 insertions(+), 92 deletions(-) create mode 100644 docs/configs/info-widgets.md delete mode 100644 docs/configs/service-widgets.md delete mode 100644 docs/widgets/info/weather.md diff --git a/docs/configs/info-widgets.md b/docs/configs/info-widgets.md new file mode 100644 index 00000000..76314396 --- /dev/null +++ b/docs/configs/info-widgets.md @@ -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 +``` diff --git a/docs/configs/service-widgets.md b/docs/configs/service-widgets.md deleted file mode 100644 index df696f61..00000000 --- a/docs/configs/service-widgets.md +++ /dev/null @@ -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 -``` diff --git a/docs/configs/services.md b/docs/configs/services.md index 9cb75177..6ef25c39 100644 --- a/docs/configs/services.md +++ b/docs/configs/services.md @@ -21,6 +21,23 @@ Groups are defined as top-level array entries. Service Groups +### 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, Service Services +### 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, diff --git a/docs/configs/settings.md b/docs/configs/settings.md index 2f387a65..7e1815bb 100644 --- a/docs/configs/settings.md +++ b/docs/configs/settings.md @@ -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 diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md index 82a7381c..bbde4cf3 100644 --- a/docs/troubleshooting/index.md +++ b/docs/troubleshooting/index.md @@ -17,7 +17,7 @@ hide: All service widgets work essentially the same, that is, homepage makes a proxied call to an API made available by that service. The majority of the time widgets don't work it is a configuration issue. Of course, sometimes things do break. Some basic steps to try: -1. Ensure that you follow the rule mentioned on https://gethomepage.dev/configs/service-widgets/. **Unless otherwise noted, URLs should not end with a / or other API path. Each widget will handle the path on its own.**. This is very important as including a trailing slash can result in an error. +1. **URLs should not end with a / or other API path. Each widget will handle the path on its own.**. Including a trailing slash can result in an error. 2. Verify the homepage installation can connect to the IP address or host you are using for the widget `url`. This is most simply achieved by pinging the server from the homepage machine, in Docker this means _from inside the container_ itself, e.g.: diff --git a/docs/widgets/authoring/proxies.md b/docs/widgets/authoring/proxies.md index 15cdb670..a8b8073e 100644 --- a/docs/widgets/authoring/proxies.md +++ b/docs/widgets/authoring/proxies.md @@ -50,7 +50,7 @@ You can also pass API keys from the widget configuration to the proxy handler, f ### `credentialedProxyHandler` -A proxy handler that makes authenticated by setting request headers. Credentials are pulled from the widgets configuration. +A proxy handler that makes authenticated requests by setting request headers. Credentials are pulled from the widgets configuration. By default the key is passed as an `X-API-Key` header. If you need to pass the key as something else, either add a case to the credentialedProxyHandler or create a new proxy handler. diff --git a/docs/widgets/index.md b/docs/widgets/index.md index 4bd45af7..fbb8edc6 100644 --- a/docs/widgets/index.md +++ b/docs/widgets/index.md @@ -28,6 +28,8 @@ Service widgets are used to display the status of a service, often a web service slug: aaaaaaabbbbb ``` +More detail on configuring service widgets can be found in the [Service Widgets Config](../configs/services.md) section. + ## Info Widgets Info widgets are used to display information in the header, often about your system or environment. Info widgets are defined your `widgets.yaml` file. Here's an example: @@ -39,3 +41,5 @@ Info widgets are used to display information in the header, often about your sys longitude: -117.51 cache: 5 ``` + +More detail on configuring info widgets can be found in the [Info Widgets Config](../configs/info-widgets.md) section. diff --git a/docs/widgets/info/openmeteo.md b/docs/widgets/info/openmeteo.md index fb5bb171..ec84ab17 100644 --- a/docs/widgets/info/openmeteo.md +++ b/docs/widgets/info/openmeteo.md @@ -3,7 +3,7 @@ title: Open-Meteo description: Open-Meteo Information Widget Configuration --- -No registration is required at all! See [https://open-meteo.com/en/docs](https://open-meteo.com/en/docs) +Homepage's recommended weather widget. No registration is required at all! See [https://open-meteo.com/en/docs](https://open-meteo.com/en/docs) ```yaml - openmeteo: diff --git a/docs/widgets/info/weather.md b/docs/widgets/info/weather.md deleted file mode 100644 index ab13b673..00000000 --- a/docs/widgets/info/weather.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Weather API -description: Weather API Information Widget Configuration ---- - -**Note: this widget is considered 'deprecated' since there is no longer a free Weather API tier for new members. See the openmeteo or openweathermap widgets for alternatives.** - -The free tier is all that's required, you will need to [register](https://www.weatherapi.com/signup.aspx) and grab your API key. - -```yaml -- weatherapi: - label: Kyiv # optional - latitude: 50.449684 - longitude: 30.525026 - units: metric # or imperial - apiKey: yourweatherapikey - cache: 5 # Time in minutes to cache API responses, to stay within limits - format: # optional, Intl.NumberFormat options - maximumFractionDigits: 1 -``` - -You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS). diff --git a/mkdocs.yml b/mkdocs.yml index a19d3b83..fa2188ad 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,8 +21,8 @@ nav: - configs/index.md - configs/settings.md - configs/bookmarks.md + - configs/info-widgets.md - configs/services.md - - configs/service-widgets.md - configs/kubernetes.md - configs/docker.md - configs/custom-css-js.md @@ -142,6 +142,7 @@ nav: - widgets/services/spoolman.md - widgets/services/stash.md - widgets/services/stocks.md + - widgets/services/suwayomi.md - widgets/services/swagdashboard.md - widgets/services/syncthing-relay-server.md - widgets/services/tailscale.md @@ -177,7 +178,6 @@ nav: - widgets/info/search.md - widgets/info/stocks.md - widgets/info/unifi_controller.md - - widgets/info/weather.md - "Learn": - widgets/authoring/index.md - "Getting Started": widgets/authoring/getting-started.md diff --git a/src/skeleton/services.yaml b/src/skeleton/services.yaml index 77626b1c..39b37926 100644 --- a/src/skeleton/services.yaml +++ b/src/skeleton/services.yaml @@ -1,6 +1,6 @@ --- # For configuration options and examples, please see: -# https://gethomepage.dev/configs/services +# https://gethomepage.dev/configs/services/ - My First Group: - My First Service: diff --git a/src/skeleton/settings.yaml b/src/skeleton/settings.yaml index 141053f5..2e828c08 100644 --- a/src/skeleton/settings.yaml +++ b/src/skeleton/settings.yaml @@ -1,6 +1,6 @@ --- # For configuration options and examples, please see: -# https://gethomepage.dev/configs/settings +# https://gethomepage.dev/configs/settings/ providers: openweathermap: openweathermapapikey diff --git a/src/skeleton/widgets.yaml b/src/skeleton/widgets.yaml index 23c8d613..b1cf0f55 100644 --- a/src/skeleton/widgets.yaml +++ b/src/skeleton/widgets.yaml @@ -1,6 +1,6 @@ --- # For configuration options and examples, please see: -# https://gethomepage.dev/configs/service-widgets +# https://gethomepage.dev/configs/info-widgets/ - resources: cpu: true