feat(docs): enable announcement config in docs.yml (#4568)

announcement
fern-api · Sep 6, 2024 · bb7ceb2 · bb7ceb2
1 parent 9d16dce
commit bb7ceb2
Show file tree

Hide file tree

Showing 15 changed files with 78 additions and 11 deletions.
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -286,6 +286,9 @@ navigation:
           - page: Navigation
             icon: fa-regular fa-compass
             path: ./pages/docs/building-your-docs/navigation.mdx
+          - page: Announcement Banner
+            icon: fa-regular fa-bullhorn
+            path: ./pages/docs/building-your-docs/announcement-banner.mdx
           - page: Links and Redirects
             icon: fa-regular fa-link
             path: ./pages/docs/building-your-docs/links-and-redirects.mdx

diff --git a/fern/pages/docs/building-your-docs/announcement-banner.mdx b/fern/pages/docs/building-your-docs/announcement-banner.mdx
@@ -0,0 +1,14 @@
+---
+title: Add an announcement banner to your docs
+subtitle: Prominently highlight new features, updates, or important information
+slug: /docs/building-your-docs/announcements
+---
+
+An announcement banner is a great way to draw attention to new features and product launches. When configured, the announcement bar appears at the top of your docs site. After the user dismisses the bar, it will reappear the next time you update the announcement.
+
+```yaml docs.yml
+announcement:
+    message: "🚀 New feature: Announcements are available! (<a href=\"https://buildwithfern.com/learn/docs/building-your-docs/announcements\" target=\"_blank\">Learn more</a>) 🚀"
+```
+
+Markdown and HTML is supported in the announcement message. You can include links, images, and other formatting. [Custom css](/learn/docs/building-your-docs/custom-css-global-js#custom-css) can be used to customize the style of the announcement.
diff --git a/packages/cli/configuration/fern/definition/docs.yml b/packages/cli/configuration/fern/definition/docs.yml
@@ -119,6 +119,8 @@ types:
           The `analytics` object allows you to configure analytics for your docs site.
           Currently, only Segment is supported.
 
+      announcement: optional<AnnouncementConfig>
+
       # navigation
       tabs: optional<map<TabId, TabConfig>>
       versions: optional<list<VersionConfig>>
@@ -975,3 +977,9 @@ types:
   PlaygroundButtonSettings:
     properties:
       href: optional<string>
+
+  AnnouncementConfig:
+    properties:
+      message:
+        type: string
+        docs: The message to display in the announcement bar. Markdown is supported.
diff --git a/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts
@@ -3,6 +3,7 @@ import { FernRegistry as CjsFdrSdk } from "@fern-fern/fdr-cjs-sdk";
 import { Audiences } from "../commons";
 import { WithoutQuestionMarks } from "../commons/WithoutQuestionMarks";
 import { DocsInstance, ExperimentalConfig, PlaygroundSettings, VersionAvailability } from "./schemas";
+import { AnnouncementConfig } from "./schemas/sdk/api/resources/docs/types/AnnouncementConfig";
 
 export interface ParsedDocsConfiguration {
     instances: DocsInstance[];
@@ -30,6 +31,7 @@ export interface ParsedDocsConfiguration {
     layout: WithoutQuestionMarks<CjsFdrSdk.docs.v1.commons.DocsLayoutConfig> | undefined;
     defaultLanguage: CjsFdrSdk.docs.v1.commons.ProgrammingLanguage | undefined;
     analyticsConfig: CjsFdrSdk.docs.v1.commons.AnalyticsConfig | undefined;
+    announcement: AnnouncementConfig | undefined;
 
     /* integrations */
     integrations: CjsFdrSdk.docs.v1.commons.IntegrationsConfig | undefined;

diff --git a/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts
@@ -130,6 +130,7 @@ export async function parseDocsConfiguration({
         navbarLinks: convertNavbarLinks(navbarLinks),
         footerLinks: convertFooterLinks(footerLinks),
         defaultLanguage,
+        announcement: rawDocsConfiguration.announcement,
 
         /* seo */
         metadata,

diff --git a/...cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnnouncementConfig.ts b/...cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnnouncementConfig.ts
@@ -0,0 +1,8 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+export interface AnnouncementConfig {
+    /** The message to display in the announcement bar. Markdown is supported. */
+    message: string;
+}
diff --git a/.../cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts b/.../cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts
@@ -13,6 +13,7 @@ export interface DocsConfiguration {
      * Currently, only Segment is supported.
      */
     analytics?: FernDocsConfig.AnalyticsConfig;
+    announcement?: FernDocsConfig.AnnouncementConfig;
     tabs?: Record<FernDocsConfig.TabId, FernDocsConfig.TabConfig>;
     versions?: FernDocsConfig.VersionConfig[];
     landingPage?: FernDocsConfig.PageConfiguration;

diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts
@@ -70,3 +70,4 @@ export * from "./IntegrationsConfig";
 export * from "./ExperimentalConfig";
 export * from "./PlaygroundSettings";
 export * from "./PlaygroundButtonSettings";
+export * from "./AnnouncementConfig";
diff --git a/...uration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnnouncementConfig.ts b/...uration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnnouncementConfig.ts
@@ -0,0 +1,20 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernDocsConfig from "../../../../api";
+import * as core from "../../../../core";
+
+export const AnnouncementConfig: core.serialization.ObjectSchema<
+    serializers.AnnouncementConfig.Raw,
+    FernDocsConfig.AnnouncementConfig
+> = core.serialization.object({
+    message: core.serialization.string(),
+});
+
+export declare namespace AnnouncementConfig {
+    interface Raw {
+        message: string;
+    }
+}
diff --git a/...guration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts b/...guration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts
@@ -15,6 +15,7 @@ export const DocsConfiguration: core.serialization.ObjectSchema<
     ),
     title: core.serialization.string().optional(),
     analytics: core.serialization.lazyObject(async () => (await import("../../..")).AnalyticsConfig).optional(),
+    announcement: core.serialization.lazyObject(async () => (await import("../../..")).AnnouncementConfig).optional(),
     tabs: core.serialization
         .record(
             core.serialization.lazy(async () => (await import("../../..")).TabId),
@@ -65,6 +66,7 @@ export declare namespace DocsConfiguration {
         instances: serializers.DocsInstance.Raw[];
         title?: string | null;
         analytics?: serializers.AnalyticsConfig.Raw | null;
+        announcement?: serializers.AnnouncementConfig.Raw | null;
         tabs?: Record<serializers.TabId.Raw, serializers.TabConfig.Raw> | null;
         versions?: serializers.VersionConfig.Raw[] | null;
         "landing-page"?: serializers.PageConfiguration.Raw | null;

diff --git a/...es/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts b/...es/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts
@@ -70,3 +70,4 @@ export * from "./IntegrationsConfig";
 export * from "./ExperimentalConfig";
 export * from "./PlaygroundSettings";
 export * from "./PlaygroundButtonSettings";
+export * from "./AnnouncementConfig";
diff --git a/packages/cli/docs-preview/package.json b/packages/cli/docs-preview/package.json
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@fern-api/docs-resolver": "workspace:*",
-    "@fern-api/fdr-sdk": "0.107.0-09e88f5f9",
+    "@fern-api/fdr-sdk": "0.107.0-58bab3016",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",
     "@fern-api/logger": "workspace:*",
@@ -62,4 +62,4 @@
     "typescript": "4.6.4",
     "vitest": "^2.0.5"
   }
-}
+}
diff --git a/packages/cli/docs-resolver/package.json b/packages/cli/docs-resolver/package.json
@@ -30,7 +30,7 @@
     "@fern-api/configuration": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-markdown-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.107.0-09e88f5f9",
+    "@fern-api/fdr-sdk": "0.107.0-58bab3016",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",
@@ -53,4 +53,4 @@
     "typescript": "4.6.4",
     "vitest": "^2.0.5"
   }
-}
+}
diff --git a/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts b/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts
@@ -257,6 +257,10 @@ export class DocsDefinitionResolver {
             footerLinks: this.parsedDocsConfig.footerLinks,
             defaultLanguage: this.parsedDocsConfig.defaultLanguage,
             analyticsConfig: this.parsedDocsConfig.analyticsConfig,
+            announcement:
+                this.parsedDocsConfig.announcement != null
+                    ? { text: this.parsedDocsConfig.announcement.message }
+                    : undefined,
             // deprecated
             logo: undefined,
             logoV2: undefined,

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml