diff --git a/website/docs/customize/interfaces/_enabled-features-list.mdx b/website/docs/customize/interfaces/_enabled-features-list.mdx new file mode 100644 index 0000000000..60df96d924 --- /dev/null +++ b/website/docs/customize/interfaces/_enabled-features-list.mdx @@ -0,0 +1,2 @@ +### Enabling/disabling features + diff --git a/website/docs/customize/interfaces/_enabledfeatureslist.mdx b/website/docs/customize/interfaces/_enabledfeatureslist.mdx deleted file mode 100644 index 54e2508e82..0000000000 --- a/website/docs/customize/interfaces/_enabledfeatureslist.mdx +++ /dev/null @@ -1,19 +0,0 @@ -### Enabling/disabling features - -The features listed below can be enabled or disabled through attributes set on the Brand. By default, all of the listed features are enabled. To disable a specific feature, set its value to `false`. - -#### `settings.enabledFeatures.apiDrawer` - -Display the API Request drawer in the upper toolbar. - -#### `settings.enabledFeatures.notificationDrawer` - -Display the Notification drawer in the upper toolbar. - -#### `settings.enabledFeatures.settings` - -Display the Settings link in the upper toolbar. - -#### `settings.enabledFeatures.search` - -Display the Search bar in the upper toolbar. diff --git a/website/docs/customize/interfaces/_generalattributes.mdx b/website/docs/customize/interfaces/_generalattributes.mdx deleted file mode 100644 index 956e69a7f4..0000000000 --- a/website/docs/customize/interfaces/_generalattributes.mdx +++ /dev/null @@ -1,43 +0,0 @@ -### General settings (both Admin and User interfaces) - -#### `settings.navbar.userDisplay` - -Configure what is shown in the top-right corner. Defaults to `username`. Available options: `username`, `name`, `email` - -#### `settings.theme.base` - -Configure the base color scheme or toggle between dark and light modes. The default setting is `automatic`, which adapts based on the user’s browser preference. Available options: `automatic`, `dark`, `light`. - -**Example**: - -``` -settings: - theme: - base: dark -``` - -#### `settings.theme.background` - -Optional CSS that is applied to the background of the User interface, for example to set a custom background color, gradient, or image. - -```yaml -settings: - theme: - background: > - background: url('https://picsum.photos/1920/1080'); - filter: blur(8px); - background-position: center; - background-repeat: no-repeat; - background-size: cover; -``` - -#### `settings.locale` - -The locale used by the interface. Set this on the default brand to configure the language instance-wide, or on user and group attributes to configure defaults for specific users or group memberships. Users can still choose their own preferred locale in user settings. - -**Example**: - -```yaml -settings: - locale: en -``` diff --git a/website/docs/customize/interfaces/_global-attributes.mdx b/website/docs/customize/interfaces/_global-attributes.mdx new file mode 100644 index 0000000000..2569abadef --- /dev/null +++ b/website/docs/customize/interfaces/_global-attributes.mdx @@ -0,0 +1,99 @@ +import ThemeAccessibilityWarning from "../../sys-mgmt/brands/_theme-accessibility-warning.mdx"; + +## Global customization + +### Navbar user display + +`settings.navbar.userDisplay: username | name | email` + +How the user's display name is formatted. **Defaults to `username`.** + +```yaml title="Changing the user's display name format" +settings: + navbar: + userDisplay: name +``` + +### Show the API Request drawer + +`settings.enabledFeatures.apiDrawer` + +Whether the API Request appears in the navigation bar. **Defaults to `true`.** + +```yaml title="Hiding the API Request drawer" +settings: + enabledFeatures: + apiDrawer: false +``` + +### Show the Notification drawer + +`settings.enabledFeatures.notificationDrawer` + +Whether the Notification drawer appears in the navigation bar. **Defaults to `true`.** + +```yaml title="Hiding the Notification drawer" +settings: + enabledFeatures: + notificationDrawer: false +``` + +### Show the user settings menu + +`settings.enabledFeatures.settings` + +Whether the user settings menu appears in the navigation bar. **Defaults to `true`.** + +```yaml title="Hiding the user settings menu" +settings: + enabledFeatures: + settings: false +``` + +### Default theme mode + +`settings.theme.base: automatic | dark | light` + +The default theme mode for the interface. When unset, authentik uses the user's preferred color scheme, or light mode if no preference is set. Setting this to `dark` or `light` enforces that color scheme for all users, regardless of their preferences. **Defaults to `automatic`** + + +```yaml title="Enforcing dark mode for the interface" +settings: + theme: + base: dark +``` + + + +### Background CSS + +`settings.theme.background: string (CSS)` + +CSS that is applied to the background of the user interface, for example to set a custom background color, gradient, or image. + +```yaml title="Setting a custom background image for the interface" +settings: + theme: + background: > + background: url('https://picsum.photos/1920/1080'); + filter: blur(8px); + background-position: center; + background-repeat: no-repeat; + background-size: cover; +``` + +For more details on customizing the theme, see our [Custom CSS documentation](../../sys-mgmt/brands/custom-css.mdx). + +### Default locale + +`settings.locale: string (BCP 47 language tag)` + +The default locale used by the interface. Set this on the default brand to configure the language instance-wide, or on user and group attributes to configure defaults for specific users or group memberships. Users can still choose their own preferred locale in user settings. **Defaults to `en` (English)** + +```yaml title="Setting the default locale to Japanese" +settings: + locale: ja-JP +``` + + +For more details, see the [Brand settings](../../sys-mgmt/brands/index.md#branding-settings) documentation. diff --git a/website/docs/customize/interfaces/_global/global.mdx b/website/docs/customize/interfaces/_global/global.mdx deleted file mode 100644 index 2180787776..0000000000 --- a/website/docs/customize/interfaces/_global/global.mdx +++ /dev/null @@ -1,11 +0,0 @@ -## Global customization - -To customize the following brand settings, log in to the Admin interface and navigate to **System > Brands > Brand settings**. - -- Title -- Logo -- Favicon -- Default flow background image -- Custom CSS - -For more details, see the [Brand settings](../../../sys-mgmt/brands/index.md#branding-settings) documentation. diff --git a/website/docs/customize/interfaces/admin/_attributes.mdx b/website/docs/customize/interfaces/admin/_attributes.mdx new file mode 100644 index 0000000000..4531e0b640 --- /dev/null +++ b/website/docs/customize/interfaces/admin/_attributes.mdx @@ -0,0 +1,25 @@ +## Admin interface settings + +The following settings are specific to the Admin interface. + +### Items per page + +`settings.pagination.perPage: integer` + +How many items should be retrieved per page. **Defaults to 20.** + +```yaml +settings: + pagination: + perPage: 50 +``` + +### Default user path + +Prefilled path to use when creating a new user in the Admin interface. **Defaults to `user`.** + +```yaml +settings: + defaults: + userPath: staff +``` diff --git a/website/docs/customize/interfaces/admin/admin-interface-attributes.png b/website/docs/customize/interfaces/admin/admin-interface-attributes.png deleted file mode 100644 index 83380c8985..0000000000 Binary files a/website/docs/customize/interfaces/admin/admin-interface-attributes.png and /dev/null differ diff --git a/website/docs/customize/interfaces/admin/index.mdx b/website/docs/customize/interfaces/admin/index.mdx index f2ef2cdb09..07b64a4964 100644 --- a/website/docs/customize/interfaces/admin/index.mdx +++ b/website/docs/customize/interfaces/admin/index.mdx @@ -3,44 +3,15 @@ title: Customize the Admin interface sidebar_label: Admin interface --- +import AdminAttributes from "./_attributes.mdx"; +import UserAttributes from "../user/_attributes.mdx"; +import EnabledFeaturesList from "../\_enabled-features-list.mdx"; +import GlobalAttributes from "../\_global-attributes.mdx"; + The Admin interface can be customized using attributes configured in [Brands](../../../sys-mgmt/brands/index.md). -To add, remove, or modify attributes for a brand, log in to the Admin interface and navigate to **System > Brands > Other global settings > Attributes**. + -Most attributes defined in a brand apply to _both_ the User and Admin interfaces. However, any settings that are specific to only the Admin interface are explicitly noted as such below. + -The following screenshot shows the syntax for setting several attributes for a brand: dark mode, a 3-column display of applications on the **Application Dashboard** page of the User interface, and hiding the API and Notifications drawers from the Admin interface toolbar. - -![](./admin-interface-attributes.png) - -## Custom settings - -The following settings for attributes are grouped by: - -- `enabledFeatures` settings -- General settings (used on both the Admin interface and the User interface) -- Admin interface only - -import Enabledfeatureslist from "../\_enabledfeatureslist.mdx"; - - - -import Generalattributes from "../\_generalattributes.mdx"; - - - -### Settings for the Admin interface only - -The following settings can only be used to customize the Admin interface, not the User interface. - -#### `settings.pagination.perPage` - -How many items should be retrieved per page. Defaults to 20. - -#### `settings.defaults.userPath` - -Default user path which is used when opening the user list. Defaults to `users`. - -import Global from "../_global/global.mdx"; - - + diff --git a/website/docs/customize/interfaces/index.md b/website/docs/customize/interfaces/index.md new file mode 100644 index 0000000000..9566775f2b --- /dev/null +++ b/website/docs/customize/interfaces/index.md @@ -0,0 +1,10 @@ +--- +title: Customize interfaces +sidebar_label: Overview +--- + +To add, remove, or modify attributes for a brand, log in to the Admin interface and navigate to **System > Brands > Other global settings > Attributes**. + +The following screenshot shows the syntax for setting several attributes for a brand: dark mode, a 3-column display of applications on the **Application Dashboard** page of the User interface, and hiding the API and Notifications drawers from the Admin interface toolbar. + +![Admin interface attributes](./interface-attributes.png) diff --git a/website/docs/customize/interfaces/interface-attributes.png b/website/docs/customize/interfaces/interface-attributes.png new file mode 100644 index 0000000000..55390dbcea Binary files /dev/null and b/website/docs/customize/interfaces/interface-attributes.png differ diff --git a/website/docs/customize/interfaces/user/_attributes.mdx b/website/docs/customize/interfaces/user/_attributes.mdx new file mode 100644 index 0000000000..31d129bea3 --- /dev/null +++ b/website/docs/customize/interfaces/user/_attributes.mdx @@ -0,0 +1,39 @@ +## Application Dashboard settings + +The following settings are specific to the Application Dashboard page. + +## Show edit option on Application Dashboard + +`settings.enabledFeatures.applicationEdit: boolean` + +If the user is a superuser, whether an _Edit Application_ option is shown on the **Application Dashboard** page. **Defaults to `false`.** + +```yaml +settings: + enabledFeatures: + applicationEdit: true +``` + +## Application Dashboard layout + +`settings.layout.type: row | 2-column | 3-column` + +Which layout to use for the **Application Dashboard** page. **Defaults to `row`.** + +```yaml +settings: + layout: + type: 3-column +``` + +### Show the Application Dashboard search bar + +`settings.enabledFeatures.search` + +Whether the Search bar appears on the Application Dashboard page. **Defaults to `true`.** + +```yaml +settings: + enabledFeatures: + search: false +``` diff --git a/website/docs/customize/interfaces/user/index.mdx b/website/docs/customize/interfaces/user/index.mdx index 54822f8cef..9817e09433 100644 --- a/website/docs/customize/interfaces/user/index.mdx +++ b/website/docs/customize/interfaces/user/index.mdx @@ -3,6 +3,10 @@ title: Customize the User interface sidebar_label: User interface --- +import EnabledFeaturesList from "../\_enabled-features-list.mdx"; +import GlobalAttributes from "../\_global-attributes.mdx"; +import UserAttributes from "./_attributes.mdx"; + The User interface can be customized using attributes configured in [Brands](../../../sys-mgmt/brands/index.md). To add, remove, or modify attributes for a brand, log in as an administrator and navigate to **System > Brands > Other global settings > Attributes**. @@ -21,24 +25,8 @@ The following settings for attributes are grouped by: - General attributes (used on both the Admin interface and the User interface) - User interface only -import Enabledfeatureslist from "../\_enabledfeatureslist.mdx"; + - + -#### `settings.enabledFeatures.applicationEdit` (User interface only) - -Display the Edit option for each application on the **Application Dashboard** page (only shown when the user is a superuser). - -import Generalattributes from "../\_generalattributes.mdx"; - - - -### Settings for the User interface only - -#### `settings.layout.type` - -Which layout to use for the **Application Dashboard** page. Defaults to `row`. Choices: `row`, `2-column`, `3-column` - -import Global from "../_global/global.mdx"; - - + diff --git a/website/docs/sidebar.mjs b/website/docs/sidebar.mjs index 9216500172..c0ac21d031 100644 --- a/website/docs/sidebar.mjs +++ b/website/docs/sidebar.mjs @@ -460,7 +460,12 @@ const items = [ //#region Interfaces type: "category", label: "Interfaces", + link: { + type: "doc", + id: "customize/interfaces/index", + }, items: [ + "customize/interfaces/index", "customize/interfaces/flow/index", "customize/interfaces/user/index", "customize/interfaces/admin/index", diff --git a/website/docs/sys-mgmt/brands/_theme-accessibility-warning.mdx b/website/docs/sys-mgmt/brands/_theme-accessibility-warning.mdx new file mode 100644 index 0000000000..8ced0982d0 --- /dev/null +++ b/website/docs/sys-mgmt/brands/_theme-accessibility-warning.mdx @@ -0,0 +1,7 @@ +:::warning Accessibility consideration + +authentik's base theme prioritizes accessibility and may adjust colors and styles based on user preferences or system settings. The browser or operating system may also override the enforced theme to respect user accessibility settings, such as high contrast mode. + +Think carefully before enforcing a specific color scheme, as it may conflict with the user's accessibility needs. Overriding accessibility settings may also have legal implications under accessibility laws and regulations in certain jurisdictions. + +::: diff --git a/website/docs/sys-mgmt/brands/custom-css.mdx b/website/docs/sys-mgmt/brands/custom-css.mdx index c83666c718..9e87f5b533 100644 --- a/website/docs/sys-mgmt/brands/custom-css.mdx +++ b/website/docs/sys-mgmt/brands/custom-css.mdx @@ -3,6 +3,8 @@ title: Custom CSS slug: /brands/custom-css --- +import ThemeAccessibilityWarning from "./_theme-accessibility-warning.mdx"; + You can add custom CSS to further customize the look of authentik. Some areas where custom CSS can be applied include: - The [flow executor](https://api.goauthentik.io/flow-executor/) (login and enrollment pages) @@ -172,13 +174,7 @@ settings: base: light ``` -:::warning Accessibility consideration - -authentik's base theme prioritizes accessibility and may adjust colors and styles based on user preferences or system settings. The browser or operating system may also override the enforced theme to respect user accessibility settings, such as high contrast mode. - -Think carefully before enforcing a specific color scheme, as it may conflict with the user's accessibility needs. Overriding accessibility settings may also have legal implications under accessibility laws and regulations in certain jurisdictions. - -::: + ### Hide the locale selector