feat(docs): add beta banner frontmatter property

fern/apis/fdr/definition/docs/latest/frontmatter.yml

@@ -75,6 +75,67 @@ types:
       tags:
         type: optional<seo.StringOrStringList>
         docs: Tags for the page. This is used to group and filter changelog pages.
+      banner:
+        type: optional<Banner>
+        docs: |
+          Displays a banner at the top of the page content. Can be set to `true` for a default warning banner,
+          a string for a warning banner with custom message, or an object for full customization.
+      beta:
+        availability: deprecated
+        type: optional<BetaBanner>
+        docs: |
+          Deprecated. Use `banner` instead. Displays a yellow warning banner at the top of the page to indicate
+          that the content is in beta or still being worked on. Can be set to `true` for a default message,
+          or provide a custom message string.
+
+  Banner:
+    discriminated: false
+    union:
+      - boolean
+      - string
+      - BannerConfig
+
+  BannerConfig:
+    properties:
+      message:
+        type: string
+        docs: The message to display in the banner.
+      intent:
+        type: optional<BannerIntent>
+        docs: The intent/style of the banner. Defaults to "warning".
+        default: warning
+      color:
+        type: optional<BannerColor>
+        docs: Optional color overrides for the banner. Use with caution as custom colors may not adapt well to dark mode.
+
+  BannerIntent:
+    enum:
+      - info
+      - warning
+      - success
+      - error
+      - note
+      - launch
+      - tip
+      - check
+
+  BannerColor:
+    properties:
+      background:
+        type: optional<string>
+        docs: Background color (CSS color value).
+      text:
+        type: optional<string>
+        docs: Text color (CSS color value).
+      border:
+        type: optional<string>
+        docs: Border color (CSS color value).
+
+  BetaBanner:
+    discriminated: false
+    union:
+      - boolean
+      - string
 
   Logo:
     discriminated: false

packages/fdr-sdk/src/docs/frontmatter.ts

@@ -39,5 +39,7 @@ export const EMPTY_FRONTMATTER: Frontmatter = {
     "jsonld:breadcrumb": undefined,
     keywords: undefined,
     logo: undefined,
-    tags: undefined
+    tags: undefined,
+    banner: undefined,
+    beta: undefined
 };

packages/fern-docs/bundle/src/components/BetaBanner.tsx

@@ -0,0 +1,85 @@
+import "server-only";
+
+import type { FernRegistry } from "@fern-api/fdr-sdk/client/types";
+import { visitDiscriminatedUnion } from "@fern-api/ui-core-utils";
+import { cn } from "@fern-docs/components/cn";
+import { Bell, Check, CheckCircle, Info, Pin, Rocket, Star, TriangleAlert } from "lucide-react";
+import type React from "react";
+import type { CSSProperties } from "react";
+
+type BannerIntent = "info" | "warning" | "success" | "error" | "note" | "launch" | "tip" | "check";
+
+export interface TopBannerProps {
+    banner: FernRegistry.docs.latest.Banner;
+    className?: string;
+}
+
+function parseBannerConfig(banner: FernRegistry.docs.latest.Banner): {
+    message: string;
+    intent: BannerIntent;
+    color?: { background?: string; text?: string; border?: string };
+} {
+    if (typeof banner === "boolean") {
+        return {
+            message: "This page is in beta and still being worked on.",
+            intent: "warning"
+        };
+    }
+
+    if (typeof banner === "string") {
+        return {
+            message: banner,
+            intent: "warning"
+        };
+    }
+
+    return {
+        message: banner.message,
+        intent: (banner.intent ?? "warning") as BannerIntent,
+        color: banner.color
+    };
+}
+
+function getIconForIntent(intent: BannerIntent): React.ReactElement {
+    return visitDiscriminatedUnion({ intent }, "intent")._visit({
+        info: () => <Info />,
+        warning: () => <Bell />,
+        success: () => <CheckCircle />,
+        error: () => <TriangleAlert />,
+        note: () => <Pin />,
+        launch: () => <Rocket />,
+        tip: () => <Star />,
+        check: () => <Check />,
+        _other: () => <Info />
+    });
+}
+
+export function TopBanner({ banner, className }: TopBannerProps) {
+    const { message, intent, color } = parseBannerConfig(banner);
+
+    const style: CSSProperties = {};
+    if (color?.background) {
+        style.backgroundColor = color.background;
+    }
+    if (color?.border) {
+        style.borderColor = color.border;
+    }
+    if (color?.text) {
+        style.color = color.text;
+    }
+
+    return (
+        <div
+            className={cn("fern-callout mb-6", className)}
+            data-intent={intent}
+            style={Object.keys(style).length > 0 ? style : undefined}
+        >
+            <div className="flex items-start space-x-4">
+                <div className="[&_svg]:size-icon-md mt-0.5 w-4">{getIconForIntent(intent)}</div>
+                <div className="flex-1 text-sm">
+                    <p className="m-0 leading-snug">{message}</p>
+                </div>
+            </div>
+        </div>
+    );
+}

packages/fern-docs/bundle/src/components/layouts/LayoutEvaluator.tsx

@@ -12,6 +12,7 @@ import { MdxContent } from "@/mdx/components/MdxContent";
 import type { MdxSerializer } from "@/server/mdx-serializer";
 
 import { asToc, getMDXExport } from "../../mdx/get-mdx-export";
+import { TopBanner } from "../BetaBanner";
 import { BuiltWithFern } from "../built-with-fern";
 import { constructPageOptions } from "../PageActionsDropdownOptions";
 import { PageHeader } from "../PageHeader";
@@ -85,6 +86,9 @@ export async function LayoutEvaluator({
         />
     );
 
+    const banner = frontmatter?.banner ?? frontmatter?.beta;
+    const topBanner = banner ? <TopBanner banner={banner} /> : null;
+
     return (
         <>
             {extractedStyles.length > 0 &&
@@ -105,6 +109,7 @@ export async function LayoutEvaluator({
                 footer={footer}
                 builtWithFern={<BuiltWithFern className="mx-auto my-8 w-fit" />}
             >
+                {topBanner}
                 <MdxContent mdx={mdx} fallback={markdown} useNextMdx={mdx?.engine === "next-remote"} />
             </AbstractLayoutEvaluatorContent>
         </>