From bb7ceb21057823db43da60bdadf756966d2f8b16 Mon Sep 17 00:00:00 2001 From: Andrew Jiang Date: Fri, 6 Sep 2024 15:02:15 -0400 Subject: [PATCH] feat(docs): enable announcement config in docs.yml (#4568) announcement --- fern/docs.yml | 3 +++ .../announcement-banner.mdx | 14 +++++++++++++ .../configuration/fern/definition/docs.yml | 8 ++++++++ .../src/docs-yml/ParsedDocsConfiguration.ts | 2 ++ .../src/docs-yml/parseDocsConfiguration.ts | 1 + .../docs/types/AnnouncementConfig.ts | 8 ++++++++ .../resources/docs/types/DocsConfiguration.ts | 1 + .../sdk/api/resources/docs/types/index.ts | 1 + .../docs/types/AnnouncementConfig.ts | 20 +++++++++++++++++++ .../resources/docs/types/DocsConfiguration.ts | 2 ++ .../resources/docs/types/index.ts | 1 + packages/cli/docs-preview/package.json | 4 ++-- packages/cli/docs-resolver/package.json | 4 ++-- .../src/DocsDefinitionResolver.ts | 4 ++++ pnpm-lock.yaml | 16 ++++++++------- 15 files changed, 78 insertions(+), 11 deletions(-) create mode 100644 fern/pages/docs/building-your-docs/announcement-banner.mdx create mode 100644 packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnnouncementConfig.ts create mode 100644 packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnnouncementConfig.ts diff --git a/fern/docs.yml b/fern/docs.yml index 74429910325..9bc1c56382e 100644 --- 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 new file mode 100644 index 00000000000..d43b20f89c2 --- /dev/null +++ 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! (Learn more) 🚀" +``` + +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 index 007a9dd7103..e4804c05bfe 100644 --- 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 + # navigation tabs: optional> versions: optional> @@ -975,3 +977,9 @@ types: PlaygroundButtonSettings: properties: href: optional + + 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 index a470ad77be0..f4e4c297bcc 100644 --- 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 | 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 index 658f043cfb5..75ef63a7a25 100644 --- 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/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnnouncementConfig.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnnouncementConfig.ts new file mode 100644 index 00000000000..142291f9b4a --- /dev/null +++ b/packages/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/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts index 04eb0f5664e..038bc717114 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts +++ b/packages/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; 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 index 5692f723ebe..0db7bd06ec1 100644 --- 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/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnnouncementConfig.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnnouncementConfig.ts new file mode 100644 index 00000000000..2577f66526e --- /dev/null +++ b/packages/cli/configuration/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/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts index 5bd199f08b3..2627e797fd9 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts +++ b/packages/cli/configuration/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 | null; versions?: serializers.VersionConfig.Raw[] | null; "landing-page"?: serializers.PageConfiguration.Raw | null; diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts index 5692f723ebe..0db7bd06ec1 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts +++ b/packages/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 index abbe3c85ea8..0b36eb1d977 100644 --- 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" } -} \ No newline at end of file +} diff --git a/packages/cli/docs-resolver/package.json b/packages/cli/docs-resolver/package.json index ec67fe304f2..787dd5fd5a8 100644 --- 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" } -} \ No newline at end of file +} diff --git a/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts b/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts index c68ee534a8a..48d070d70d1 100644 --- 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 index adc34df74c6..df13cb41897 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -3104,6 +3104,8 @@ importers: packages/cli/cli/dist/dev: {} + packages/cli/cli/dist/prod: {} + packages/cli/configuration: dependencies: '@fern-api/core-utils': @@ -3247,8 +3249,8 @@ importers: specifier: workspace:* version: link:../docs-resolver '@fern-api/fdr-sdk': - specifier: 0.107.0-09e88f5f9 - version: 0.107.0-09e88f5f9(typescript@4.6.4) + specifier: 0.107.0-58bab3016 + version: 0.107.0-58bab3016(typescript@4.6.4) '@fern-api/fs-utils': specifier: workspace:* version: link:../../commons/fs-utils @@ -3350,8 +3352,8 @@ importers: specifier: workspace:* version: link:../docs-markdown-utils '@fern-api/fdr-sdk': - specifier: 0.107.0-09e88f5f9 - version: 0.107.0-09e88f5f9(typescript@4.6.4) + specifier: 0.107.0-58bab3016 + version: 0.107.0-58bab3016(typescript@4.6.4) '@fern-api/fs-utils': specifier: workspace:* version: link:../../commons/fs-utils @@ -6476,8 +6478,8 @@ packages: '@exodus/schemasafe@1.0.0': resolution: {integrity: sha512-2cyupPIZI69HQxEAPllLXBjQp4njDKkOjYRCYxvMZe3/LY9pp9fBM3Tb1wiFAdP6Emo4v3OEbCLGj6u73Q5KLw==} - '@fern-api/fdr-sdk@0.107.0-09e88f5f9': - resolution: {integrity: sha512-9vVSuRIWgqRlJFvSbGCuOE3jbDIUGOWXkUA/ra9ELgDlqH0Uo5NZYC9AHcQze2wu5P5X5NOjQbwPNQp6B5Jy+g==} + '@fern-api/fdr-sdk@0.107.0-58bab3016': + resolution: {integrity: sha512-cQOi7Ye5/R0RkPFD0AmZOZjo5k8NISWveJjZb2dGbGgmVxZNsO9Es2Ze1034a930pIXBhd6+Shc4/8NU/m+1hw==} '@fern-api/venus-api-sdk@0.0.38': resolution: {integrity: sha512-1JjuctZwyPu4jN51bBqjIy+uCBPGa/ROcDfqN0UnGeVEW7NyztkGh/qOFwnN6K07VMMql1AIF4Zov+MVqTPwmw==} @@ -13528,7 +13530,7 @@ snapshots: '@exodus/schemasafe@1.0.0': {} - '@fern-api/fdr-sdk@0.107.0-09e88f5f9(typescript@4.6.4)': + '@fern-api/fdr-sdk@0.107.0-58bab3016(typescript@4.6.4)': dependencies: dayjs: 1.11.11 fast-deep-equal: 3.1.3