docs: banners

website/docs/how-to/how-to-create-and-display-banners.md

@@ -0,0 +1,44 @@
+---
+title: How to create and display banners
+---
+
+:::info Availability
+
+Banners were introduced as a beta feature in **Unleash 5.6** and are only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in **Unleash 5.7**.
+
+:::
+
+
+This guide takes you through [how to create](#creating-banners "how to create banners") and [display](#displaying-banners "how to display banners") [banners](../reference/banners.md).
+
+## Creating banners
+
+### Step 1: Navigate to the banners page {#create-step-1}
+
+Navigate to the _banners_ page in the admin UI (available at the URL `/admin/banners`). Use the _settings_ button in the navigation menu and select "banners".
+
+![The admin UI admin menu with the Banners item highlighted.](/img/create-banners-step-1.png)
+
+### Step 2: Use the "new banner" button {#create-step-2}
+
+Use the "new banner" button to open the "new banner" form.
+
+![The "banners" table with the "new banner" button highlighted.](/img/create-banners-step-2.png)
+
+### Step 3: Fill in the banner form {#create-step-3}
+
+Choose whether the banner should be enabled right away. If enabled, the banner will be visible to all users in your Unleash instance. Select the banner type, icon, and write the message that you'd like to see displayed on the banner. The message and dialog fields support [Markdown](https://www.markdownguide.org/basic-syntax/). Optionally, you can also configure a banner action for user interactivity. For a full overview of all the banner options, consult the [banners reference documentation](../reference/banners).
+
+You'll be able to preview the banner at the top as you fill in the form.
+
+Once you're satisfied, use the "add banner" button to create the banner.
+
+![The banner form filled with some example data, and the "add banner" button highlighted at the bottom.](/img/create-banners-step-3.png)
+
+## Displaying banners
+
+You can choose whether a banner is currently displayed to all users of your Unleash instance by toggling the "enabled" switch on the banner table. 
+
+Alternatively, you can edit the banner by using the "edit" button on the banner table and then toggle the "banner status" switch.
+
+![The "banners" table with some example data, and the "enable" switch highlighted.](/img/create-banners-display.png)

website/docs/reference/banners.md

@@ -0,0 +1,85 @@
+---
+title: Banners
+---
+
+:::info Availability
+
+Banners were introduced as a beta feature in **Unleash 5.6** and are only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in **Unleash 5.7**.
+
+:::
+
+Banners allow you to configure and display internal messages that all users of your Unleash instance can see and interact with. They are displayed at the top of the Unleash UI, and can be configured to be interactive.
+
+![Banners table](/img/banners-table.png)
+
+A common use case could be to have some pre-configured banners that you can enable when you need to communicate something to your users. For example, you could have a banner that you enable when you're doing maintenance on your Unleash instance, and another banner that you enable when you're running a survey.
+
+In order to create and display a banner, you can follow the [how to create and display banners](../how-to/how-to-create-and-display-banners.md) guide.
+
+## Banner status
+
+Banners can be enabled or disabled at any time. For more information on how to enable or disable a banner, see the section on [displaying banners](../how-to/how-to-create-and-display-banners.md#displaying-banners).
+
+| Option      | Description                                                                      |
+| ----------- | -------------------------------------------------------------------------------- |
+| **Enabled** | Whether the banner is currently displayed to all users of your Unleash instance. |
+
+## Configuration
+
+Banners can be configured with the following options:
+
+| Option      | Description                                                                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Type**    | The type of banner, which controls the banner's color and its icon, if using the default icon option.                                        |
+| **Icon**    | The icon displayed on the banner. This can be the default for the banner type, a [custom icon](#custom-icon), or hidden by selecting "None". |
+| **Message** | The banner's message. Supports [Markdown](https://www.markdownguide.org/basic-syntax/).                                                      |
+
+### Custom icon
+
+To further personalize your banner, you can configure it with a custom icon.
+
+To use a custom icon in your banner:
+1. Select "Custom" in the icon dropdown.
+2. Enter the name of the desired [Material Symbol](https://fonts.google.com/icons).
+    - For example, for the "Rocket Launch" icon, enter `rocket_launch` in the custom icon field.
+
+| Option          | Description                                                                                              |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| **Custom icon** | The custom icon to be displayed on the banner, using [Material Symbols](https://fonts.google.com/icons). |
+
+## Banner action
+
+You can set up an action for your banner:
+
+| Option            | Description                                                                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Banner action** | The action activated when a user interacts with the banner link. Defaults to "None". Options include a [link](#link) or a [dialog](#dialog). |
+
+### Link
+
+When choosing the link action, a link will be displayed on the banner that directs users to a specified URL.
+
+The configured URL can be absolute, as in e.g. `https://docs.getunleash.io/`, or relative as in e.g. `/admin/network`. Absolute URLs will open in a new tab.
+
+| Option   | Description                                               |
+| -------- | --------------------------------------------------------- |
+| **URL**  | The URL to open when the user uses the banner link.       |
+| **Text** | The text to display on the banner link.                   |
+
+### Dialog
+
+When opting for a dialog action, an interactable link appears on the banner which opens a dialog with additional information.
+
+| Option             | Description                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| **Text**           | The text to display on the banner link.                                                                 |
+| **Dialog title**   | The title to display on the dialog.                                                                     |
+| **Dialog content** | The content to display on the dialog. Supports [Markdown](https://www.markdownguide.org/basic-syntax/). |
+
+## Sticky banner
+
+For added visibility, banners can be configured to be "sticky," ensuring they remain at the top of the Unleash UI, even after scrolling the page. This is useful for banners that you want to make sure that your users see and interact with.
+
+| Option     | Description                                                |
+| ---------- | ---------------------------------------------------------- |
+| **Sticky** | Whether the banner is sticky on the screen when scrolling. |

website/sidebars.js

@@ -155,6 +155,7 @@ module.exports = {
                         'how-to/how-to-add-feature-flag-naming-patterns',
                         'how-to/how-to-capture-impression-data',
                         'how-to/how-to-create-feature-toggles',
+                        'how-to/how-to-create-and-display-banners',
                         'how-to/how-to-define-custom-context-fields',
                         'how-to/how-to-use-custom-strategies',
                         'how-to/how-to-schedule-feature-releases',
@@ -393,6 +394,7 @@ module.exports = {
                         'reference/activation-strategies',
                         'reference/api-tokens-and-client-keys',
                         'reference/archived-toggles',
+                        'reference/banners',
                         'reference/event-log',
                         'reference/event-types',
                         'reference/impression-data',
@@ -456,4 +458,4 @@ module.exports = {
             ],
         },
     ],
-};
+};