feat: top banner via configuration

docs/configuration.mdx

@@ -223,6 +223,42 @@ or [Brand Icons](https://fontawesome.com/search?o=r&f=brands), for example:
 </Tabs>
 </Property>
 
+<Property name="topBanner" type="object">
+An object containing the configuration for a top banner notification on your interface. This feature allows for the display of information, warnings, or error messages in a prominent banner format. Depending on the type of message you need to convey, the `type` field should be adjusted accordingly. All properties must be defined for the banner to display properly, except for the `type` field, which defaults to 'info' if not specified.
+
+<Tabs
+  values={[
+    { label: 'JSON', value: 'json' },
+    { label: 'YAML', value: 'yaml' },
+  ]}
+>
+  <TabItem value="json">
+  ```json title="Example topBanner config"
+  {
+    "topBanner": {
+      "active": true,
+      "type": "error",
+      "message": "This is a sample error message."
+    }
+  }
+ </TabItem>
+  <TabItem value="yaml">
+  ```yaml title="Example topBanner config"
+  topBanner:
+    active: true
+    type: error
+    message: "This is a sample error message."
+  ```
+  </TabItem>
+</Tabs>
+
+### Properties
+
+1. active: A boolean indicating whether the banner is active or not. When true, the banner will be visible.
+2. type: An enum specifying the type of banner to display. It can be one of the following values: 'error', 'info', 'warning', 'success'. If not provided, it defaults to 'info'.
+3. message: A string representing the message text displayed on the banner. This should be a clear and concise message relating to the information or feedback you want to communicate to the users.
+   </Property>
+
 <hr />
 
 <Property name="docsearch" type="object">

package.json

@@ -2,7 +2,7 @@
   "private": true,
   "scripts": {
     "dev": "concurrently \"yarn dev:api\" \"yarn dev:website\"",
-    "dev:website": "cd website && yarn dev",
+    "dev:website": "cd website-v3 && yarn dev",
     "dev:api": "cd api && yarn dev",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,mdx}\"",
     "check:linting": "eslint . --max-warnings=0",

website-v3/src/bundle.ts

@@ -32,6 +32,13 @@ const $BundleConfig = z.object({
       indexName: z.string(),
     })
     .optional(),
+  topBanner: z
+    .object({
+      active: z.boolean(),
+      type: z.enum(['error', 'info', 'warning', 'success']).default('info'),
+      message: z.string(),
+    })
+    .optional(),
   sidebar: z.union([$SidebarArray, $SidebarRecord]),
   locales: z.array(z.string()),
   headerDepth: z.number(),

website-v3/src/pages/[owner]/[repository]/[...path].astro

@@ -20,6 +20,14 @@ import type { GetBundleResponse } from 'src/bundle';
 import { isExternalLink, replaceMoustacheVariables, ensureLeadingSlash } from 'src/utils';
 import { trackPageRequest } from 'src/plausible';
 import domains from '../../../../../domains.json';
+import {
+  Error as ErrorCallout,
+  Info as InfoCallout,
+  Success as SuccessCallout,
+  Warning as WarningCallout,
+} from '@components/mdx/callouts';
+import type React from 'react';
+import type { ReactNode } from 'react';
 
 let { owner, repository, path } = Astro.params;
 let ref: string | undefined;
@@ -69,9 +77,14 @@ status = statusCodes[code];
 // Set the status code for the request
 Astro.response.status = status;
 
+let TopBannerCallout: React.FC<{ children?: ReactNode }> | null = null;
+let topBannerMessage: string = '';
+
 if (response?.code === 'OK') {
   const { frontmatter, config, source, baseBranch, code, headings } = response!.data;
 
+  topBannerMessage = config.topBanner?.message || '';
+
   // Handle a frontmatter redirect
   const redirect = frontmatter.redirect;
   if (redirect && isExternalLink(redirect)) {
@@ -122,6 +135,21 @@ if (response?.code === 'OK') {
     sidebar = config.sidebar;
   }
 
+  if (config.topBanner?.active) {
+    switch (config.topBanner.type) {
+      case 'error':
+        TopBannerCallout = ErrorCallout;
+      case 'info':
+        TopBannerCallout = InfoCallout;
+      case 'success':
+        TopBannerCallout = SuccessCallout;
+      case 'warning':
+        TopBannerCallout = WarningCallout;
+      default:
+        TopBannerCallout = InfoCallout;
+    }
+  }
+
   // Set the context store.
   context.set({
     owner,
@@ -215,6 +243,9 @@ function codeToTitle(code: GetBundleResponse['code']) {
         <div class="lg:pl-[20rem]">
           <div class="flex flex-row items-stretch gap-12 pt-9">
             <div class="relative mx-auto max-w-3xl flex-grow overflow-auto text-slate-500 dark:text-slate-400 xl:-ml-12 xl:max-w-[47rem] xl:pr-1 xl:pl-12">
+              {TopBannerCallout && topBannerMessage ? (
+                <TopBannerCallout>{topBannerMessage}</TopBannerCallout>
+              ) : null}
               <Markdown />
               <PreviousNext />
               <Footer />