diff --git a/authentication.md b/authentication.md index 8a74ce8..4b8e0e6 100644 --- a/authentication.md +++ b/authentication.md @@ -146,6 +146,8 @@ appConfig: clientId: 'dashy' ``` +Note that if you are using Keycloak V 17 or older, you will also need to set `legacySupport: true` (also under `appConfig.auth.keycloak`). This is because the API endpoint was updated in later versions. + ### 4. Add groups and roles (Optional) Keycloak allows you to assign users roles and groups. You can use these values to configure who can access various sections in Dashy. Keycloak server administration and configuration is a deep topic; please refer to the [server admin guide](https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-and-access-using-roles-and-groups) to see details about creating and assigning roles and groups. diff --git a/configuring.md b/configuring.md index e09bc4a..2ef8268 100644 --- a/configuring.md +++ b/configuring.md @@ -163,6 +163,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`serverUrl`** | `string` | Required | The URL (or URL/ IP + Port) where your keycloak server is running **`realm`** | `string` | Required | The name of the realm (must already be created) that you want to use **`clientId`** | `string` | Required | The Client ID of the client you created for use with Dashy +**`legacySupport`** | `boolean` | _Optional_ | If using Keycloak 17 or older, then set this to `true` **[⬆️ Back to Top](#configuring)** diff --git a/credits.md b/credits.md index 02251a2..e3b1229 100644 --- a/credits.md +++ b/credits.md @@ -13,7 +13,7 @@ - emlazzarin + emlazzarin
Eddy Lazzarin @@ -56,7 +56,7 @@ - shadowking001 + shadowking001
LawrenceP. @@ -68,6 +68,13 @@ Kieren Connell + + + Antiz96 +
+ Robin Candau + + ratty222 @@ -81,7 +88,8 @@
Undefined - + + jtfinley72 @@ -171,7 +179,7 @@ stanly0726
- stanly0726 + Stanly0726 diff --git a/pages-and-sections.md b/pages-and-sections.md index ad19faf..f55c62f 100644 --- a/pages-and-sections.md +++ b/pages-and-sections.md @@ -56,3 +56,43 @@ The following example shows creating a config, publishing it as a [Gist](https:/ Only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo. Note that since page paths are required by the router, they are set at build-time, not run-time, and so a rebuild (happens automatically) is required for changes to page paths to take effect (this only applies to changes to the `pages` array, rebuild isn't required for editing page content). + + +## Sub-Items + +A normal section will contain zero or more items, for example: + +```yaml +- name: Coding + icon: far fa-code + items: + - title: GitHub + url: https://github.com/ + - title: StackOverflow + url: http://stackoverflow.com/ +``` + +But items can also be grouped together, referred to as sub-items. This is useful for a group of less frequently used items, which you don't want to take up too much space, or for action buttons (_coming soon_). + +Item groups may also have an optional title. + +```yaml +- name: Coding + icon: far fa-code + items: + - title: Normal Item 1 + - title: Normal Item 2 + - subItems: + - title: JavaScript + url: https://developer.mozilla.org + icon: si-javascript + - title: TypeScript + url: https://www.typescriptlang.org/docs + icon: si-typescript + - title: Svelt + url: https://svelte.dev/docs + icon: si-svelte + - title: Go + url: https://go.dev/doc + icon: si-go +``` diff --git a/troubleshooting.md b/troubleshooting.md index 4ba5729..b69d48e 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -30,12 +30,13 @@ - [Diagnosing Widget Errors](#widget-errors) - [Fixing Widget CORS Errors](#widget-cors-errors) - [Weather Forecast Widget 401](#weather-forecast-widget-401) -- [Keycloak Redirect Error](#keycloak-redirect-error) +- [Font Awesome Icons not Displaying](#font-awesome-icons-not-displaying) - [How-To Open Browser Console](#how-to-open-browser-console) - [Git Contributions not Displaying](#git-contributions-not-displaying) --- + ## `Refused to Connect` in Modal or Workspace View This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. @@ -214,6 +215,13 @@ You should also ensure that Keycloak is correctly configured, with a user, realm For more details on how to set headers, see the [Example Headers](/docs/management.md#setting-headers) in the management docs, or reference the documentation for your proxy. +If you're running in Kubernetes, you will need to enable CORS ingress rules, see [docs](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors), e.g: + +``` +nginx.ingress.kubernetes.io/cors-allow-origin: "https://dashy.example.com" +nginx.ingress.kubernetes.io/enable-cors: "true" +``` + See also: #479, #409, #507, #491, #341, #520 --- @@ -412,22 +420,19 @@ A future update will be pushed out, to use a free weather forecasting API. --- -## Keycloak Redirect Error +## Font Awesome Icons not Displaying -Firstly, ensure that in your Keycloak instance you have populated the Valid Redirect URIs field ([screenshot](https://user-images.githubusercontent.com/1862727/148599768-db4ee4f8-72c5-402d-8f00-051d999e6267.png)) with the URL to your Dashy instance. +Usually, Font Awesome will be automatically enabled if one or more of your icons are using Font-Awesome. If this is not happening, then you can always manually enable (or disable) Font Awesome by setting: [`appConfig`](/docs/configuring.md#appconfig-optional).`enableFontAwesome` to `true`. -You may need to specify CORS headers on your Keycloak instance, to allow requests coming from Dashy, e.g: +If you are trying to use a premium icon, then you must have a [Pro License](https://fontawesome.com/plans). You'll then need to specify your Pro plan API key under `appConfig.fontAwesomeKey`. You can find this key, by logging into your FA account, navigate to Account → [Kits](https://fontawesome.com/kits) → New Kit → Copy Kit Code. The code is a 10-digit alpha-numeric code, and is also visible within the new kit's URL, for example: `81e48ce079`. -``` -Access-Control-Allow-Origin: https://dashy.example.com -``` +Be sure that you're specifying the icon category and name correctly. You're icon should look be `[category] fa-[icon-name]`. The following categories are supported: `far` _(regular)_, `fas` _(solid)_, `fal`_(light)_, `fad` _(duo-tone)_ and `fab`_(brands)_. With the exception of brands, you'll usually want all your icons to be in from same category, so they look uniform. -If you're running in Kubernetes, you will need to enable CORS ingress rules, see [docs](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors), e.g: +Ensure the icon you are trying to use, is available within [FontAwesome Version 5](https://fontawesome.com/v5/search). -``` -nginx.ingress.kubernetes.io/cors-allow-origin: "https://dashy.example.com" -nginx.ingress.kubernetes.io/enable-cors: "true" -``` +Examples: `fab fa-raspberry-pi`, `fas fa-database`, `fas fa-server`, `fas fa-ethernet` + +Finally, check the [browser console](#how-to-open-browser-console) for any error messages, and raise a ticket if the issue persists. --- diff --git a/widgets.md b/widgets.md index 02f2d13..1f8e1fd 100644 --- a/widgets.md +++ b/widgets.md @@ -97,6 +97,7 @@ A simple, live-updating time and date widget with time-zone support. All fields **`format`** | `string` | _Optional_ | A country code for displaying the date and time in local format.
Specified as `[ISO-3166]-[ISO-639]`, for example: `en-AU`. See [here](https://www.fincher.org/Utilities/CountryLanguageList.shtml) for a full list of locales. Defaults to the browser / device's region **`customCityName`** | `string` | _Optional_ | By default the city from the time-zone is shown, but setting this value will override that text **`hideDate`** | `boolean` | _Optional_ | If set to `true`, the date and city will not be shown. Defaults to `false` +**`hideSeconds`** | `boolean` | _Optional_ | If set to `true`, seconds will not be shown. Defaults to `false` ##### Example @@ -713,6 +714,7 @@ Show recent scores and upcoming matches from your favourite sports team. Data is **`pastOrFuture`** | `string` | __Optional__ | Set to `past` to show scores for recent games, or `future` to show upcoming games. Defaults to `past`. You can change this within the UI **`apiKey`** | `string` | __Optional__ | Optionally specify your API key, which you can sign up for at [TheSportsDB.com](https://www.thesportsdb.com/) **`limit`** | `number` | __Optional__ | To limit output to a certain number of matches, defaults to `15` +**`hideImage`** | `boolean` | __Optional__ | Set to `true` to not render the team / match banner image, defaults to `false` ##### Example